--- /dev/null
+This describes how to build the documentation found in the
+org.eclipse.tracecompass.*.doc.* plugins.
+
+
+Your Eclipse environment first needs to have the "Mylyn Wikitext" plugin
+installed. It can be found in the default Eclipse repository, under
+"Collaboration".
+
+Once that is installed, you should be able to use the manual Eclipse builder to
+generate the doc : select the and individual doc plugin and choose, in the
+top-menu, "Project -> Build Project".
+
+It uses the build.xml Ant script, but it's recommended to run it from within
+Eclipse, since the builder will pass some environment variables that the script
+needs.
+
+You might get a warning from build.properties because of a missing file. This
+file gets generated with the rest of the doc, so once you have run these steps
+(and refreshed the project if needed), the warning should disappear.
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
+<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
+<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
+<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
+<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.doc.dev" type="4"/> </resources>}"/>
+<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS">
+<listEntry value="/org.eclipse.tracecompass.doc.dev/build.xml"/>
+</listAttribute>
+<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES">
+<listEntry value="1"/>
+</listAttribute>
+<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
+<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.doc.dev"/>
+<stringAttribute key="org.eclipse.jdt.launching.SOURCE_PATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.doc.dev/build.xml}"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
+<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
+<stringAttribute key="process_factory_id" value="org.eclipse.ant.ui.remoteAntProcessFactory"/>
+</launchConfiguration>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.eclipse.tracecompass.doc.dev</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
+ <triggers>clean,full,incremental,</triggers>
+ <arguments>
+ <dictionary>
+ <key>LaunchConfigHandle</key>
+ <value><project>/.externalToolBuilders/org.eclipse.linuxtools.tmf.help build.xml [Builder].launch</value>
+ </dictionary>
+ <dictionary>
+ <key>incclean</key>
+ <value>true</value>
+ </dictionary>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.ManifestBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.SchemaBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.pde.PluginNature</nature>
+ <nature>org.eclipse.mylyn.wikitext.ui.wikiTextNature</nature>
+ </natures>
+</projectDescription>
--- /dev/null
+eclipse.preferences.version=1
+encoding/<project>=UTF-8
--- /dev/null
+eclipse.preferences.version=1
+line.separator=\n
--- /dev/null
+eclipse.preferences.version=1
+org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false
--- /dev/null
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-Vendor: %Bundle-Vendor
+Bundle-Version: 0.1.0.qualifier
+Bundle-Localization: plugin
+Bundle-SymbolicName: org.eclipse.tracecompass.doc.dev;singleton:=true
+Require-Bundle: org.eclipse.help
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+<title>About</title>
+</head>
+<body lang="EN-US">
+<h2>About This Content</h2>
+
+<p>June 5, 2006</p>
+<h3>License</h3>
+
+<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
+at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+For purposes of the EPL, "Program" will mean the Content.</p>
+
+<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
+being redistributed by another party ("Redistributor") and different terms and conditions may
+apply to your use of any object code in the Content. Check the Redistributor's license that was
+provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
+
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+/* following font face declarations need to be removed for DBCS */
+
+
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
+pre { font-family: Courier, monospace}
+
+/* end font face declarations */
+
+/* following font size declarations should be OK for DBCS */
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
+pre { font-size: 12pt}
+
+/* end font size declarations */
+
+body { background: #FFFFFF}
+h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
+h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
+h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
+h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
+h5 { font size: 13.5pt; }
+p { font-size: 12pt; }
+pre { margin-left: 6; font-size: 9pt }
+
+a:link { color: #006699 }
+a:visited { color: #996699 }
+a:hover { color: #006699 }
+
+ul { margin-top: 0; margin-bottom: 10 }
+li { margin-top: 0; margin-bottom: 0 }
+li p { margin-top: 0; margin-bottom: 0 }
+ol { margin-top: 0; margin-bottom: 10 }
+dl { margin-top: 0; margin-bottom: 10 }
+dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
+dd { margin-top: 0; margin-bottom: 0 }
+strong { font-weight: bold}
+em { font-style: italic}
+var { font-style: italic}
+div.revision { border-left-style: solid; border-left-width: thin;
+ border-left-color: #7B68EE; padding-left:5 }
+th { font-weight: bold }
+.hidden {
+ display: none;
+}
+
+/* Mike Behm's addition to the style sheet */
+.userinput { font-family: monospace; }
+.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
+.notetitle {
+ color: #000000;
+ font-family: helvetica, arial, sans-serif;
+ font-weight: bold;
+ }
+div.linux {display:none;}
+.firsterm {font-style:italic;}
+
+.typewriter {font-family:monospace;}
+.bold {font-weight:600;}
+.linethrough {text-decoration: line-through;}
+.underline {text-decoration: underline;}
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+bin.includes = plugin.xml,\
+ META-INF/,\
+ about.html,\
+ plugin.properties,\
+ book.css,\
+ doc/
+jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
+ platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
+src.includes = about.html
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="org.eclipse.tracecompass.doc.dev" default="build" basedir=".">
+ <description>
+ Generate Eclipse help content for the Trace Compass Developer Guide
+ </description>
+
+ <property name="ug.title" value="Trace Compass Developer Guide" />
+
+ <path id="wikitext.tasks.classpath">
+ <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
+ <fileset dir="${osgi.syspath}" erroronmissingdir="false">
+ <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
+ <include name="com.google.guava_*.jar" />
+ </fileset>
+
+ <!-- For Maven builds: use the compile_classpath -->
+ <pathelement path="${compile_classpath}" />
+ </path>
+
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
+ <!-- Different location in more recent versions of Mylyn (Luna ?) -->
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
+
+ <target name="build" description="Generate Eclipse help content for the Linux Tools TMF Developer Guide">
+ <wikitext-to-eclipse-help markupLanguage="MediaWiki"
+ validate="true"
+ failonvalidationerror="true"
+ overwrite="true"
+ multipleOutputFiles="true"
+ navigationimages="true"
+ title="${ug.title}"
+ formatoutput="true"
+ helpPrefix="doc">
+ <fileset dir="doc">
+ <include name="Developer-Guide.mediawiki" />
+ </fileset>
+ <stylesheet url="book.css" />
+ </wikitext-to-eclipse-help>
+ <antcall target="test" />
+ </target>
+
+ <target name="test" description="Verify that all of the HTML files are well-formed XML">
+ <!--
+ Don't bother with DTD validation: we only care if the files are well-formed.
+ We therefore provide an empty DTD
+ -->
+ <xmlvalidate lenient="true">
+ <fileset dir="doc">
+ <include name="**/*.html" />
+ </fileset>
+ <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
+ </xmlvalidate>
+ </target>
+
+ <target name ="clean" description="Delete all generated files">
+ <delete failonerror="false">
+ <fileset dir="doc" includes="**/*.html" />
+ <fileset dir="doc" includes="**/*.xml" />
+ </delete>
+ </target>
+
+</project>
--- /dev/null
+*.html
+*.xml
--- /dev/null
+
+= Introduction =
+
+The purpose of the '''Tracing Monitoring Framework (TMF)''' is to facilitate the integration of tracing and monitoring tools into Eclipse, to provide out-of-the-box generic functionalities/views and provide extension mechanisms of the base functionalities for application specific purposes.
+
+= Implementing a New Trace Type =
+
+The framework can easily be extended to support more trace types. To make a new trace type, one must define the following items:
+
+* The event type
+* The trace reader
+* The trace context
+* The trace location
+* The ''org.eclipse.linuxtools.tmf.core.tracetype'' plug-in extension point
+* (Optional) The ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point
+
+The '''event type''' must implement an ''ITmfEvent'' or extend a class that implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event type must contain all the data of an event. The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class will supply many background operations so that the reader only needs to implement certain functions. The '''trace context''' can be seen as the internals of an iterator. It is required by the trace reader to parse events as it iterates the trace and to keep track of its rank and location. It can have a timestamp, a rank, a file position, or any other element, it should be considered to be ephemeral. The '''trace location''' is an element that is cloned often to store checkpoints, it is generally persistent. It is used to rebuild a context, therefore, it needs to contain enough information to unambiguously point to one and only one event. Finally the ''tracetype'' plug-in extension associates a given trace, non-programmatically to a trace type for use in the UI.
+
+== An Example: Nexus-lite parser ==
+
+=== Description of the file ===
+
+This is a very small subset of the nexus trace format, with some changes to make it easier to read. There is one file. This file starts with 64 Strings containing the event names, then an arbitrarily large number of events. The events are each 64 bits long. the first 32 are the timestamp in microseconds, the second 32 are split into 6 bits for the event type, and 26 for the data payload.
+
+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.
+
+<pre>
+Startup,Stop,Load,Add, ... ,reserved\n
+</pre>
+
+Then there will be the events in this format
+
+{| width= "85%"
+|style="width: 50%; background-color: #ffffcc;"|timestamp (32 bits)
+|style="width: 10%; background-color: #ffccff;"|type (6 bits)
+|style="width: 40%; background-color: #ccffcc;"|payload (26 bits)
+|-
+|style="background-color: #ffcccc;" colspan="3"|64 bits total
+|}
+
+all events will be the same size (64 bits).
+
+=== NexusLite Plug-in ===
+
+Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to '''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
+
+Now the structure for the Nexus trace Plug-in is set up.
+
+Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in '''META-INF''', selecting the '''Dependencies''' tab and '''Add ...''' '''org.eclipse.linuxtools.tmf.core''' and '''org.eclipse.linuxtools.tmf.ui'''.
+
+[[Image:images/NTTAddDepend.png]]<br>
+[[Image:images/NTTSelectProjects.png]]<br>
+
+Now the project can access TMF classes.
+
+=== Trace Event ===
+
+The '''TmfEvent''' class will work for this example. No code required.
+
+=== Trace Reader ===
+
+The trace reader will extend a '''TmfTrace''' class.
+
+It will need to implement:
+
+* validate (is the trace format valid?)
+
+* initTrace (called as the trace is opened
+
+* seekEvent (go to a position in the trace and create a context)
+
+* getNext (implemented in the base class)
+
+* parseEvent (read the next element in the trace)
+
+For reference, there is an example implementation of the Nexus Trace file in
+org.eclipse.linuxtools.tracing.examples.core.trace.nexus.NexusTrace.java.
+
+In this example, the '''validate''' function checks first checks if the file
+exists, then makes sure that it is really a file, and not a directory. Then we
+attempt to read the file header, to make sure that it is really a Nexus Trace.
+If that check passes, we return a TmfValidationStatus with a confidence of 20.
+
+Typically, TmfValidationStatus confidences should range from 1 to 100. 1 meaning
+"there is a very small chance that this trace is of this type", and 100 meaning
+"it is this type for sure, and cannot be anything else". At run-time, the
+auto-detection will pick the the type which returned the highest confidence. So
+checks of the type "does the file exist?" should not return a too high
+confidence.
+
+Here we used a confidence of 20, to leave "room" for more specific trace types
+in the Nexus format that could be defined in TMF.
+
+The '''initTrace''' function will read the event names, and find where the data starts. After this, the number of events is known, and since each event is 8 bytes long according to the specs, the seek is then trivial.
+
+The '''seek''' here will just reset the reader to the right location.
+
+The '''parseEvent''' method needs to parse and return the current event and store the current location.
+
+The '''getNext''' method (in base class) will read the next event and update the context. It calls the '''parseEvent''' method to read the event and update the location. It does not need to be overridden and in this example it is not. The sequence of actions necessary are parse the next event from the trace, create an '''ITmfEvent''' with that data, update the current location, call '''updateAttributes''', update the context then return the event.
+
+Traces will typically implement an index, to make seeking faster. The index can
+be rebuilt every time the trace is opened. Alternatively, it can be saved to
+disk, to make future openings of the same trace quicker. To do so, the trace
+object can implement the '''ITmfPersistentlyIndexable''' interface.
+
+=== Trace Context ===
+
+The trace context will be a '''TmfContext'''
+
+=== Trace Location ===
+
+The trace location will be a long, representing the rank in the file. The '''TmfLongLocation''' will be the used, once again, no code is required.
+
+=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point ===
+
+One should implement the ''tmf.core.tracetype'' extension in their own plug-in.
+In this example, the Nexus trace plug-in will be modified.
+
+The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants users to access the given event type. It can be updated in the Eclipse plug-in editor.
+
+# In Extensions tab, add the '''org.eclipse.linuxtools.tmf.core.tracetype''' extension point.
+[[Image:images/NTTExtension.png]]<br>
+[[Image:images/NTTTraceType.png]]<br>
+[[Image:images/NTTExtensionPoint.png]]<br>
+
+# 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'''.
+
+[[Image:images/NTTAddType.png]]<br>
+
+The '''id''' is the unique identifier used to refer to the trace.
+
+The '''name''' is the field that shall be displayed when a trace type is selected.
+
+The '''trace type''' is the canonical path refering to the class of the trace.
+
+The '''event type''' is the canonical path refering to the class of the events of a given trace.
+
+The '''category''' (optional) is the container in which this trace type will be stored.
+
+# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that,
+'''right click''' on the extension then in the context menu, go to
+'''New >''', '''type'''.
+
+The '''tracetype''' here is the '''id''' of the
+''org.eclipse.linuxtools.tmf.core.tracetype'' mentioned above.
+
+The '''icon''' is the image to associate with that trace type.
+
+In the end, the extension menu should look like this.
+
+[[Image:images/NTTPluginxmlComplete.png]]<br>
+
+== Other Considerations ==
+The ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable'' provides additional features that are active when the event class (defined in '''event type''') implements certain additional interfaces.
+
+=== Collapsing of repetitive events ===
+By implementing the interface ''org.eclipse.linuxtools.tmf.core.event.collapse.ITmfCollapsibleEvent'' the events table will allow to collapse repetitive events by selecting the menu item '''Collapse Events''' after pressing the right mouse button in the table.
+
+== Best Practices ==
+
+* Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
+* Reuse as much code as possible, it makes the trace format much easier to maintain.
+* Use Eclipse's editor instead of editing the XML directly.
+* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
+* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
+** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
+
+== Download the Code ==
+
+The described example is available in the
+org.eclipse.linuxtools.tracing.examples.(tests.)trace.nexus packages with a
+trace generator and a quick test case.
+
+== Optional Trace Type Attributes ==
+
+After defining the trace type as described in the previous chapters it is possible to define optional attributes for the trace type.
+
+=== Default Editor ===
+
+The '''defaultEditor''' attribute of the '''org.eclipse.tmf.ui.tracetypeui'''
+extension point allows for configuring the editor to use for displaying the
+events. If omitted, the ''TmfEventsEditor'' is used as default.
+
+To configure an editor, first add the '''defaultEditor''' attribute to the trace
+type in the extension definition. This can be done by selecting the trace type
+in the plug-in manifest editor. Then click the right mouse button and select
+'''New -> defaultEditor''' in the context sensitive menu. Then select the newly
+added attribute. Now you can specify the editor id to use on the right side of
+the manifest editor. For example, this attribute could be used to implement an
+extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
+could use the ''TmfEventsEditor''' to display the events in a table as usual and
+other pages can display other aspects of the trace.
+
+=== Events Table Type ===
+
+The '''eventsTableType''' attribute of the '''org.eclipse.tmf.ui.tracetypeui'''
+extension point allows for configuring the events table class to use in the
+default events editor. If omitted, the default events table will be used.
+
+To configure a trace type specific events table, first add the
+'''eventsTableType''' attribute to the trace type in the extension definition.
+This can be done by selecting the trace type in the plug-in manifest editor.
+Then click the right mouse button and select '''New -> eventsTableType''' in the
+context sensitive menu. Then select the newly added attribute and click on
+''class'' on the right side of the manifest editor. The new class wizard will
+open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable''.
+
+By using this attribute, a table with different columns than the default columns
+can be defined. See the class org.eclipse.linuxtools.internal.lttng2.kernel.ui.viewers.events.Lttng2EventsTable
+for an example implementation.
+
+= View Tutorial =
+
+This tutorial describes how to create a simple view using the TMF framework and the SWTChart library. SWTChart is a library based on SWT that can draw several types of charts including a line chart which we will use in this tutorial. We will create a view containing a line chart that displays time stamps on the X axis and the corresponding event values on the Y axis.
+
+This tutorial will cover concepts like:
+
+* Extending TmfView
+* Signal handling (@TmfSignalHandler)
+* Data requests (TmfEventRequest)
+* SWTChart integration
+
+'''Note''': TMF 3.0.0 provides base implementations for generating SWTChart viewers and views. For more details please refer to chapter [[#TMF Built-in Views and Viewers]].
+
+=== Prerequisites ===
+
+The tutorial is based on Eclipse 4.4 (Eclipse Luna), TMF 3.0.0 and SWTChart 0.7.0. If you are using TMF from the source repository, SWTChart is already included in the target definition file (see org.eclipse.linuxtools.lttng.target). You can also install it manually by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
+
+=== Creating an Eclipse UI Plug-in ===
+
+To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
+[[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
+
+[[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
+
+[[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
+
+=== Creating a View ===
+
+To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
+[[Image:images/SelectManifest.png]]<br>
+
+Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf.core'' and press '''OK'''<br>
+Following the same steps, add ''org.eclipse.linuxtools.tmf.ui'' and ''org.swtchart''.<br>
+[[Image:images/AddDependencyTmfUi.png]]<br>
+
+Change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the view extension ''org.eclipse.ui.views'' and press '''Finish'''.<br>
+[[Image:images/AddViewExtension1.png]]<br>
+
+To create a view, click the right mouse button. Then select '''New -> view'''<br>
+[[Image:images/AddViewExtension2.png]]<br>
+
+A new view entry has been created. Fill in the fields ''id'' 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>
+[[Image:images/FillSampleViewExtension.png]]<br>
+
+This will generate an empty class. Once the quick fixes are applied, the following code is obtained:
+
+<pre>
+package org.eclipse.linuxtools.tmf.sample.ui;
+
+import org.eclipse.swt.widgets.Composite;
+import org.eclipse.ui.part.ViewPart;
+
+public class SampleView extends TmfView {
+
+ public SampleView(String viewName) {
+ super(viewName);
+ // TODO Auto-generated constructor stub
+ }
+
+ @Override
+ public void createPartControl(Composite parent) {
+ // TODO Auto-generated method stub
+
+ }
+
+ @Override
+ public void setFocus() {
+ // TODO Auto-generated method stub
+
+ }
+
+}
+</pre>
+
+This creates an empty view, however the basic structure is now is place.
+
+=== Implementing a view ===
+
+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.
+
+==== Adding an Empty Chart ====
+
+First, we can add an empty chart to the view and initialize some of its components.
+
+<pre>
+ private static final String SERIES_NAME = "Series";
+ private static final String Y_AXIS_TITLE = "Signal";
+ private static final String X_AXIS_TITLE = "Time";
+ private static final String FIELD = "value"; // The name of the field that we want to display on the Y axis
+ private static final String VIEW_ID = "org.eclipse.linuxtools.tmf.sample.ui.view";
+ private Chart chart;
+ private ITmfTrace currentTrace;
+
+ public SampleView() {
+ super(VIEW_ID);
+ }
+
+ @Override
+ public void createPartControl(Composite parent) {
+ chart = new Chart(parent, SWT.BORDER);
+ chart.getTitle().setVisible(false);
+ chart.getAxisSet().getXAxis(0).getTitle().setText(X_AXIS_TITLE);
+ chart.getAxisSet().getYAxis(0).getTitle().setText(Y_AXIS_TITLE);
+ chart.getSeriesSet().createSeries(SeriesType.LINE, SERIES_NAME);
+ chart.getLegend().setVisible(false);
+ }
+
+ @Override
+ public void setFocus() {
+ chart.setFocus();
+ }
+</pre>
+
+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>
+[[Image:images/RunEclipseApplication.png]]<br>
+
+A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample View'''.<br>
+[[Image:images/ShowViewOther.png]]<br>
+
+You should now see a view containing an empty chart<br>
+[[Image:images/EmptySampleView.png]]<br>
+
+==== Signal Handling ====
+
+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.
+
+<pre>
+ @TmfSignalHandler
+ public void traceSelected(final TmfTraceSelectedSignal signal) {
+
+ }
+</pre>
+
+==== Requesting Data ====
+
+Then we need to actually gather data from the trace. This is done asynchronously using a ''TmfEventRequest''
+
+<pre>
+ @TmfSignalHandler
+ public void traceSelected(final TmfTraceSelectedSignal signal) {
+ // Don't populate the view again if we're already showing this trace
+ if (currentTrace == signal.getTrace()) {
+ return;
+ }
+ currentTrace = signal.getTrace();
+
+ // Create the request to get data from the trace
+
+ TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
+ TmfTimeRange.ETERNITY, 0, ITmfEventRequest.ALL_DATA,
+ ITmfEventRequest.ExecutionType.BACKGROUND) {
+
+ @Override
+ public void handleData(ITmfEvent data) {
+ // Called for each event
+ super.handleData(data);
+ }
+
+ @Override
+ public void handleSuccess() {
+ // Request successful, not more data available
+ super.handleSuccess();
+ }
+
+ @Override
+ public void handleFailure() {
+ // Request failed, not more data available
+ super.handleFailure();
+ }
+ };
+ ITmfTrace trace = signal.getTrace();
+ trace.sendRequest(req);
+ }
+</pre>
+
+==== Transferring Data to the Chart ====
+
+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.
+
+<pre>
+ TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
+ TmfTimeRange.ETERNITY, 0, ITmfEventRequest.ALL_DATA,
+ ITmfEventRequest.ExecutionType.BACKGROUND) {
+
+ ArrayList<Double> xValues = new ArrayList<Double>();
+ ArrayList<Double> yValues = new ArrayList<Double>();
+
+ @Override
+ public void handleData(ITmfEvent data) {
+ // Called for each event
+ super.handleData(data);
+ ITmfEventField field = data.getContent().getField(FIELD);
+ if (field != null) {
+ yValues.add((Double) field.getValue());
+ xValues.add((double) data.getTimestamp().getValue());
+ }
+ }
+
+ @Override
+ public void handleSuccess() {
+ // Request successful, not more data available
+ super.handleSuccess();
+
+ final double x[] = toArray(xValues);
+ final double y[] = toArray(yValues);
+
+ // This part needs to run on the UI thread since it updates the chart SWT control
+ Display.getDefault().asyncExec(new Runnable() {
+
+ @Override
+ public void run() {
+ chart.getSeriesSet().getSeries()[0].setXSeries(x);
+ chart.getSeriesSet().getSeries()[0].setYSeries(y);
+
+ chart.redraw();
+ }
+
+ });
+ }
+
+ /**
+ * Convert List<Double> to double[]
+ */
+ private double[] toArray(List<Double> list) {
+ double[] d = new double[list.size()];
+ for (int i = 0; i < list.size(); ++i) {
+ d[i] = list.get(i);
+ }
+
+ return d;
+ }
+ };
+</pre>
+
+==== Adjusting the Range ====
+
+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.
+
+<pre>
+
+ ArrayList<Double> xValues = new ArrayList<Double>();
+ ArrayList<Double> yValues = new ArrayList<Double>();
+ private double maxY = -Double.MAX_VALUE;
+ private double minY = Double.MAX_VALUE;
+ private double maxX = -Double.MAX_VALUE;
+ private double minX = Double.MAX_VALUE;
+
+ @Override
+ public void handleData(ITmfEvent data) {
+ super.handleData(data);
+ ITmfEventField field = data.getContent().getField(FIELD);
+ if (field != null) {
+ Double yValue = (Double) field.getValue();
+ minY = Math.min(minY, yValue);
+ maxY = Math.max(maxY, yValue);
+ yValues.add(yValue);
+
+ double xValue = (double) data.getTimestamp().getValue();
+ xValues.add(xValue);
+ minX = Math.min(minX, xValue);
+ maxX = Math.max(maxX, xValue);
+ }
+ }
+
+ @Override
+ public void handleSuccess() {
+ super.handleSuccess();
+ final double x[] = toArray(xValues);
+ final double y[] = toArray(yValues);
+
+ // This part needs to run on the UI thread since it updates the chart SWT control
+ Display.getDefault().asyncExec(new Runnable() {
+
+ @Override
+ public void run() {
+ chart.getSeriesSet().getSeries()[0].setXSeries(x);
+ chart.getSeriesSet().getSeries()[0].setYSeries(y);
+
+ // Set the new range
+ if (!xValues.isEmpty() && !yValues.isEmpty()) {
+ chart.getAxisSet().getXAxis(0).setRange(new Range(0, x[x.length - 1]));
+ chart.getAxisSet().getYAxis(0).setRange(new Range(minY, maxY));
+ } else {
+ chart.getAxisSet().getXAxis(0).setRange(new Range(0, 1));
+ chart.getAxisSet().getYAxis(0).setRange(new Range(0, 1));
+ }
+ chart.getAxisSet().adjustRange();
+
+ chart.redraw();
+ }
+ });
+ }
+</pre>
+
+==== Formatting the Time Stamps ====
+
+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.
+
+<pre>
+ @Override
+ public void createPartControl(Composite parent) {
+ ...
+
+ chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
+ }
+
+ public class TmfChartTimeStampFormat extends SimpleDateFormat {
+ private static final long serialVersionUID = 1L;
+ @Override
+ public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition) {
+ long time = date.getTime();
+ toAppendTo.append(TmfTimestampFormat.getDefaulTimeFormat().format(time));
+ return toAppendTo;
+ }
+ }
+
+ @TmfSignalHandler
+ public void timestampFormatUpdated(TmfTimestampFormatUpdateSignal signal) {
+ // Called when the time stamp preference is changed
+ chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
+ chart.redraw();
+ }
+</pre>
+
+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.
+
+<pre>
+ @Override
+ public void createPartControl(Composite parent) {
+ ...
+
+ ITmfTrace trace = getActiveTrace();
+ if (trace != null) {
+ traceSelected(new TmfTraceSelectedSignal(this, trace));
+ }
+ }
+</pre>
+
+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>
+
+[[Image:images/SampleView.png]]<br>
+
+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.
+
+== TMF Built-in Views and Viewers ==
+
+TMF provides base implementations for several types of views and viewers for generating custom X-Y-Charts, Time Graphs, or Trees. They are well integrated with various TMF features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the TMF UI plug-in ''org.eclipse.linuxtools.tmf.ui''. See below for a list of relevant java packages:
+
+* Generic
+** ''org.eclipse.linuxtools.tmf.ui.views'': Common TMF view base classes
+* X-Y-Chart
+** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts'': Common base classes for X-Y-Chart viewers based on SWTChart
+** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.barcharts'': Base classes for bar charts
+** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.linecharts'': Base classes for line charts
+* Time Graph View
+** ''org.eclipse.linuxtools.tmf.ui.widgets.timegraph'': Base classes for time graphs e.g. Gantt-charts
+* Tree Viewer
+** ''org.eclipse.linuxtools.tmf.ui.viewers.tree'': Base classes for TMF specific tree viewers
+
+Several features in TMF and the Eclipse LTTng integration are using this framework and can be used as example for further developments:
+* X-Y- Chart
+** ''org.eclipse.linuxtools.internal.lttng2.ust.ui.views.memusage.MemUsageView.java''
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageView.java''
+** ''org.eclipse.linuxtools.tracing.examples.ui.views.histogram.NewHistogramView.java''
+* Time Graph View
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.controlflow.ControlFlowView.java''
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.resources.ResourcesView.java''
+* Tree Viewer
+** ''org.eclipse.linuxtools.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
+** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageComposite.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.
+
+The TMF Signal Manager handles registration of components and the broadcasting of signals to their intended receivers.
+
+Components can register as VIP receivers which will ensure they will receive the signal before non-VIP receivers.
+
+== Sending Signals ==
+
+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.
+
+<pre>
+TmfExampleSignal signal = new TmfExampleSignal(this, ...);
+TmfSignalManager.dispatchSignal(signal);
+</pre>
+
+If the sender is an instance of the class TmfComponent, the broadcast method can be used:
+
+<pre>
+TmfExampleSignal signal = new TmfExampleSignal(this, ...);
+broadcast(signal);
+</pre>
+
+== Receiving Signals ==
+
+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.
+
+<pre>
+TmfSignalManager.register(this);
+TmfSignalManager.registerVIP(this);
+</pre>
+
+If the receiver is an instance of the class TmfComponent, it is automatically registered as a normal receiver in the constructor.
+
+When the receiver is destroyed or disposed, it should deregister itself from the signal manager.
+
+<pre>
+TmfSignalManager.deregister(this);
+</pre>
+
+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.
+
+<pre>
+@TmfSignalHandler
+public void example(TmfExampleSignal signal) {
+ ...
+}
+</pre>
+
+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.
+
+== Signal Throttling ==
+
+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.
+
+The signal throttler must first be initialized:
+
+<pre>
+final int delay = 100; // in ms
+TmfSignalThrottler throttler = new TmfSignalThrottler(this, delay);
+</pre>
+
+Then the sending of signals should be queued through the throttler:
+
+<pre>
+TmfExampleSignal signal = new TmfExampleSignal(this, ...);
+throttler.queue(signal);
+</pre>
+
+When the throttler is no longer needed, it should be disposed:
+
+<pre>
+throttler.dispose();
+</pre>
+
+== Signal Reference ==
+
+The following is a list of built-in signals defined in the framework.
+
+=== TmfStartSynchSignal ===
+
+''Purpose''
+
+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.
+
+''Senders''
+
+Sent by TmfSignalManager before dispatching a signal to all receivers.
+
+''Receivers''
+
+Received by TmfDataProvider.
+
+=== TmfEndSynchSignal ===
+
+''Purpose''
+
+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.
+
+''Senders''
+
+Sent by TmfSignalManager after dispatching a signal to all receivers.
+
+''Receivers''
+
+Received by TmfDataProvider.
+
+=== TmfTraceOpenedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a trace has been opened in an editor.
+
+''Senders''
+
+Sent by a TmfEventsEditor instance when it is created.
+
+''Receivers''
+
+Received by TmfTrace, TmfExperiment, TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
+
+=== TmfTraceSelectedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a trace has become the currently selected trace.
+
+''Senders''
+
+Sent by a TmfEventsEditor instance when it receives focus. Components can send this signal to make a trace editor be brought to front.
+
+''Receivers''
+
+Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
+
+=== TmfTraceClosedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a trace editor has been closed.
+
+''Senders''
+
+Sent by a TmfEventsEditor instance when it is disposed.
+
+''Receivers''
+
+Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
+
+=== TmfTraceRangeUpdatedSignal ===
+
+''Purpose''
+
+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.
+
+''Senders''
+
+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.
+
+''Receivers''
+
+Received by TmfTrace, TmfExperiment and components that process trace events. Components that need to process trace events should handle this signal.
+
+=== TmfTraceUpdatedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that new events have been indexed for a trace.
+
+''Senders''
+
+Sent by TmfCheckpointIndexer when new events have been indexed and the number of events has changed.
+
+''Receivers''
+
+Received by components that need to be notified of a new trace event count.
+
+=== TmfTimeSynchSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a new time or time range has been
+selected. It contains a begin and end time. If a single time is selected then
+the begin and end time are the same.
+
+''Senders''
+
+Sent by any component that allows the user to select a time or time range.
+
+''Receivers''
+
+Received by any component that needs to be notified of the currently selected time or time range.
+
+=== TmfRangeSynchSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a new time range window has been set.
+
+''Senders''
+
+Sent by any component that allows the user to set a time range window.
+
+''Receivers''
+
+Received by any component that needs to be notified of the current visible time range window.
+
+=== TmfEventFilterAppliedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a filter has been applied to a trace.
+
+''Senders''
+
+Sent by TmfEventsTable when a filter is applied.
+
+''Receivers''
+
+Received by any component that shows trace data and needs to be notified of applied filters.
+
+=== TmfEventSearchAppliedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that a search has been applied to a trace.
+
+''Senders''
+
+Sent by TmfEventsTable when a search is applied.
+
+''Receivers''
+
+Received by any component that shows trace data and needs to be notified of applied searches.
+
+=== TmfTimestampFormatUpdateSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the timestamp format preference has been updated.
+
+''Senders''
+
+Sent by TmfTimestampFormat when the default timestamp format preference is changed.
+
+''Receivers''
+
+Received by any component that needs to refresh its display for the new timestamp format.
+
+=== TmfStatsUpdatedSignal ===
+
+''Purpose''
+
+This signal is used to indicate that the statistics data model has been updated.
+
+''Senders''
+
+Sent by statistic providers when new statistics data has been processed.
+
+''Receivers''
+
+Received by statistics viewers and any component that needs to be notified of a statistics update.
+
+=== TmfPacketStreamSelected ===
+
+''Purpose''
+
+This signal is used to indicate that the user has selected a packet stream to analyze.
+
+''Senders''
+
+Sent by the Stream List View when the user selects a new packet stream.
+
+''Receivers''
+
+Received by views that analyze packet streams.
+
+== Debugging ==
+
+TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.linuxtools.tmf.core''', and check the '''signal''' item.
+
+All signals sent and received will be logged to the file TmfTrace.log located in the Eclipse home directory.
+
+= Generic State System =
+
+== Introduction ==
+
+The Generic State System is a utility available in TMF to track different states
+over the duration of a trace. It works by first sending some or all events of
+the trace into a state provider, which defines the state changes for a given
+trace type. Once built, views and analysis modules can then query the resulting
+database of states (called "state history") to get information.
+
+For example, let's suppose we have the following sequence of events in a kernel
+trace:
+
+ 10 s, sys_open, fd = 5, file = /home/user/myfile
+ ...
+ 15 s, sys_read, fd = 5, size=32
+ ...
+ 20 s, sys_close, fd = 5
+
+Now let's say we want to implement an analysis module which will track the
+amount of bytes read and written to each file. Here, of course the sys_read is
+interesting. However, by just looking at that event, we have no information on
+which file is being read, only its fd (5) is known. To get the match
+fd5 = /home/user/myfile, we have to go back to the sys_open event which happens
+5 seconds earlier.
+
+But since we don't know exactly where this sys_open event is, we will have to go
+back to the very start of the trace, and look through events one by one! This is
+obviously not efficient, and will not scale well if we want to analyze many
+similar patterns, or for very large traces.
+
+A solution in this case would be to use the state system to keep track of the
+amount of bytes read/written to every *filename* (instead of every file
+descriptor, like we get from the events). Then the module could ask the state
+system "what is the amount of bytes read for file "/home/user/myfile" at time
+16 s", and it would return the answer "32" (assuming there is no other read
+than the one shown).
+
+== High-level components ==
+
+The State System infrastructure is composed of 3 parts:
+* The state provider
+* The central state system
+* The storage backend
+
+The state provider is the customizable part. This is where the mapping from
+trace events to state changes is done. This is what you want to implement for
+your specific trace type and analysis type. It's represented by the
+ITmfStateProvider interface (with a threaded implementation in
+AbstractTmfStateProvider, which you can extend).
+
+The core of the state system is exposed through the ITmfStateSystem and
+ITmfStateSystemBuilder interfaces. The former allows only read-only access and
+is typically used for views doing queries. The latter also allows writing to the
+state history, and is typically used by the state provider.
+
+Finally, each state system has its own separate backend. This determines how the
+intervals, or the "state history", are saved (in RAM, on disk, etc.) You can
+select the type of backend at construction time in the TmfStateSystemFactory.
+
+== Definitions ==
+
+Before we dig into how to use the state system, we should go over some useful
+definitions:
+
+=== Attribute ===
+
+An attribute is the smallest element of the model that can be in any particular
+state. When we refer to the "full state", in fact it means we are interested in
+the state of every single attribute of the model.
+
+=== Attribute Tree ===
+
+Attributes in the model can be placed in a tree-like structure, a bit like files
+and directories in a file system. However, note that an attribute can always
+have both a value and sub-attributes, so they are like files and directories at
+the same time. We are then able to refer to every single attribute with its
+path in the tree.
+
+For example, in the attribute tree for LTTng kernel traces, we use the following
+attributes, among others:
+
+<pre>
+|- Processes
+| |- 1000
+| | |- PPID
+| | |- Exec_name
+| |- 1001
+| | |- PPID
+| | |- Exec_name
+| ...
+|- CPUs
+ |- 0
+ | |- Status
+ | |- Current_pid
+ ...
+</pre>
+
+In this model, the attribute "Processes/1000/PPID" refers to the PPID of process
+with PID 1000. The attribute "CPUs/0/Status" represents the status (running,
+idle, etc.) of CPU 0. "Processes/1000/PPID" and "Processes/1001/PPID" are two
+different attribute, even though their base name is the same: the whole path is
+the unique identifier.
+
+The value of each attribute can change over the duration of the trace,
+independently of the other ones, and independently of its position in the tree.
+
+The tree-like organization is optional, all attributes could be at the same
+level. But it's possible to put them in a tree, and it helps make things
+clearer.
+
+=== Quark ===
+
+In addition to a given path, each attribute also has a unique integer
+identifier, called the "quark". To continue with the file system analogy, this
+is like the inode number. When a new attribute is created, a new unique quark
+will be assigned automatically. They are assigned incrementally, so they will
+normally be equal to their order of creation, starting at 0.
+
+Methods are offered to get the quark of an attribute from its path. The API
+methods for inserting state changes and doing queries normally use quarks
+instead of paths. This is to encourage users to cache the quarks and re-use
+them, which avoids re-walking the attribute tree over and over, which avoids
+unneeded hashing of strings.
+
+=== State value ===
+
+The path and quark of an attribute will remain constant for the whole duration
+of the trace. However, the value carried by the attribute will change. The value
+of a specific attribute at a specific time is called the state value.
+
+In the TMF implementation, state values can be integers, longs, doubles, or strings.
+There is also a "null value" type, which is used to indicate that no particular
+value is active for this attribute at this time, but without resorting to a
+'null' reference.
+
+Any other type of value could be used, as long as the backend knows how to store
+it.
+
+Note that the TMF implementation also forces every attribute to always carry the
+same type of state value. This is to make it simpler for views, so they can
+expect that an attribute will always use a given type, without having to check
+every single time. Null values are an exception, they are always allowed for all
+attributes, since they can safely be "unboxed" into all types.
+
+=== State change ===
+
+A state change is the element that is inserted in the state system. It consists
+of:
+* a timestamp (the time at which the state change occurs)
+* an attribute (the attribute whose value will change)
+* a state value (the new value that the attribute will carry)
+
+It's not an object per se in the TMF implementation (it's represented by a
+function call in the state provider). Typically, the state provider will insert
+zero, one or more state changes for every trace event, depending on its event
+type, payload, etc.
+
+Note, we use "timestamp" here, but it's in fact a generic term that could be
+referred to as "index". For example, if a given trace type has no notion of
+timestamp, the event rank could be used.
+
+In the TMF implementation, the timestamp is a long (64-bit integer).
+
+=== State interval ===
+
+State changes are inserted into the state system, but state intervals are the
+objects that come out on the other side. Those are stocked in the storage
+backend. A state interval represents a "state" of an attribute we want to track.
+When doing queries on the state system, intervals are what is returned. The
+components of a state interval are:
+* Start time
+* End time
+* State value
+* Quark
+
+The start and end times represent the time range of the state. The state value
+is the same as the state value in the state change that started this interval.
+The interval also keeps a reference to its quark, although you normally know
+your quark in advance when you do queries.
+
+=== State history ===
+
+The state history is the name of the container for all the intervals created by
+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.
+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.
+
+=== Construction phase ===
+
+Before we can query a state system, we need to build the state history first. To
+do so, trace events are sent one-by-one through the state provider, which in
+turn sends state changes to the central component, which then creates intervals
+and stores them in the backend. This is called the construction phase.
+
+Note that the state system needs to receive its events into chronological order.
+This phase will end once the end of the trace is reached.
+
+Also note that it is possible to query the state system while it is being build.
+Any timestamp between the start of the trace and the current end time of the
+state system (available with ITmfStateSystem#getCurrentEndTime()) is a valid
+timestamp that can be queried.
+
+=== Queries ===
+
+As mentioned previously, when doing queries on the state system, the returned
+objects will be state intervals. In most cases it's the state *value* we are
+interested in, but since the backend has to instantiate the interval object
+anyway, there is no additional cost to return the interval instead. This way we
+also get the start and end times of the state "for free".
+
+There are two types of queries that can be done on the state system:
+
+==== Full queries ====
+
+A full query means that we want to retrieve the whole state of the model for one
+given timestamp. As we remember, this means "the state of every single attribute
+in the model". As parameter we only need to pass the timestamp (see the API
+methods below). The return value will be an array of intervals, where the offset
+in the array represents the quark of each attribute.
+
+==== Single queries ====
+
+In other cases, we might only be interested in the state of one particular
+attribute at one given timestamp. For these cases it's better to use a
+single query. For a single query. we need to pass both a timestamp and a
+quark in parameter. The return value will be a single interval, representing
+the state that this particular attribute was at that time.
+
+Single queries are typically faster than full queries (but once again, this
+depends on the backend that is used), but not by much. Even if you only want the
+state of say 10 attributes out of 200, it could be faster to use a full query
+and only read the ones you need. Single queries should be used for cases where
+you only want one attribute per timestamp (for example, if you follow the state
+of the same attribute over a time range).
+
+
+== Relevant interfaces/classes ==
+
+This section will describe the public interface and classes that can be used if
+you want to use the state system.
+
+=== Main classes in org.eclipse.linuxtools.tmf.core.statesystem ===
+
+==== ITmfStateProvider / AbstractTmfStateProvider ====
+
+ITmfStateProvider is the interface you have to implement to define your state
+provider. This is where most of the work has to be done to use a state system
+for a custom trace type or analysis type.
+
+For first-time users, it's recommended to extend AbstractTmfStateProvider
+instead. This class takes care of all the initialization mumbo-jumbo, and also
+runs the event handler in a separate thread. You will only need to implement
+eventHandle, which is the call-back that will be called for every event in the
+trace.
+
+For an example, you can look at StatsStateProvider in the TMF tree, or at the
+small example below.
+
+==== TmfStateSystemFactory ====
+
+Once you have defined your state provider, you need to tell your trace type to
+build a state system with this provider during its initialization. This consists
+of overriding TmfTrace#buildStateSystems() and in there of calling the method in
+TmfStateSystemFactory that corresponds to the storage backend you want to use
+(see the section [[#Comparison of state system backends]]).
+
+You will have to pass in parameter the state provider you want to use, which you
+should have defined already. Each backend can also ask for more configuration
+information.
+
+You must then call registerStateSystem(id, statesystem) to make your state
+system visible to the trace objects and the views. The ID can be any string of
+your choosing. To access this particular state system, the views or modules will
+need to use this ID.
+
+Also, don't forget to call super.buildStateSystems() in your implementation,
+unless you know for sure you want to skip the state providers built by the
+super-classes.
+
+You can look at how LttngKernelTrace does it for an example. It could also be
+possible to build a state system only under certain conditions (like only if the
+trace contains certain event types).
+
+
+==== ITmfStateSystem ====
+
+ITmfStateSystem is the main interface through which views or analysis modules
+will access the state system. It offers a read-only view of the state system,
+which means that no states can be inserted, and no attributes can be created.
+Calling TmfTrace#getStateSystems().get(id) will return you a ITmfStateSystem
+view of the requested state system. The main methods of interest are:
+
+===== getQuarkAbsolute()/getQuarkRelative() =====
+
+Those are the basic quark-getting methods. The goal of the state system is to
+return the state values of given attributes at given timestamps. As we've seen
+earlier, attributes can be described with a file-system-like path. The goal of
+these methods is to convert from the path representation of the attribute to its
+quark.
+
+Since quarks are created on-the-fly, there is no guarantee that the same
+attributes will have the same quark for two traces of the same type. The views
+should always query their quarks when dealing with a new trace or a new state
+provider. Beyond that however, quarks should be cached and reused as much as
+possible, to avoid potentially costly string re-hashing.
+
+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.
+
+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
+the origin quark, followed by a String varagrs which represent the relative path
+to the final attribute.
+
+These two methods will throw an AttributeNotFoundException if trying to access
+an attribute that does not exist in the model.
+
+These methods also imply that the view has the knowledge of how the attribute
+tree is organized. This should be a reasonable hypothesis, since the same
+analysis plugin will normally ship both the state provider and the view, and
+they will have been written by the same person. In other cases, it's possible to
+use getSubAttributes() to explore the organization of the attribute tree first.
+
+===== waitUntilBuilt() =====
+
+This is a simple method used to block the caller until the construction phase of
+this state system is done. If the view prefers to wait until all information is
+available before starting to do queries (to get all known attributes right away,
+for example), this is the guy to call.
+
+===== queryFullState() =====
+
+This is the method to do full queries. As mentioned earlier, you only need to
+pass a target timestamp in parameter. It will return a List of state intervals,
+in which the offset corresponds to the attribute quark. This will represent the
+complete state of the model at the requested time.
+
+===== querySingleState() =====
+
+The method to do single queries. You pass in parameter both a timestamp and an
+attribute quark. This will return the single state matching this
+timestamp/attribute pair.
+
+Other methods are available, you are encouraged to read their Javadoc and see if
+they can be potentially useful.
+
+==== ITmfStateSystemBuilder ====
+
+ITmfStateSystemBuilder is the read-write interface to the state system. It
+extends ITmfStateSystem itself, so all its methods are available. It then adds
+methods that can be used to write to the state system, either by creating new
+attributes of inserting state changes.
+
+It is normally reserved for the state provider and should not be visible to
+external components. However it will be available in AbstractTmfStateProvider,
+in the field 'ss'. That way you can call ss.modifyAttribute() etc. in your state
+provider to write to the state.
+
+The main methods of interest are:
+
+===== getQuark*AndAdd() =====
+
+getQuarkAbsoluteAndAdd() and getQuarkRelativeAndAdd() work exactly like their
+non-AndAdd counterparts in ITmfStateSystem. The difference is that the -AndAdd
+versions will not throw any exception: if the requested attribute path does not
+exist in the system, it will be created, and its newly-assigned quark will be
+returned.
+
+When in a state provider, the -AndAdd version should normally be used (unless
+you know for sure the attribute already exist and don't want to create it
+otherwise). This means that there is no need to define the whole attribute tree
+in advance, the attributes will be created on-demand.
+
+===== modifyAttribute() =====
+
+This is the main state-change-insertion method. As was explained before, a state
+change is defined by a timestamp, an attribute and a state value. Those three
+elements need to be passed to modifyAttribute as parameters.
+
+Other state change insertion methods are available (increment-, push-, pop- and
+removeAttribute()), but those are simply convenience wrappers around
+modifyAttribute(). Check their Javadoc for more information.
+
+===== closeHistory() =====
+
+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.
+
+If you use the AbstractTmfStateProvider, it will call closeHistory()
+automatically when it reaches the end of the trace.
+
+=== Other relevant interfaces ===
+
+==== o.e.l.tmf.core.statevalue.ITmfStateValue ====
+
+This is the interface used to represent state values. Those are used when
+inserting state changes in the provider, and is also part of the state intervals
+obtained when doing queries.
+
+The abstract TmfStateValue class contains the factory methods to create new
+state values of either int, long, double or string types. To retrieve the real
+object inside the state value, one can use the .unbox* methods.
+
+Note: Do not instantiate null values manually, use TmfStateValue.nullValue()
+
+==== o.e.l.tmf.core.interval.ITmfStateInterval ====
+
+This is the interface to represent the state intervals, which are stored in the
+state history backend, and are returned when doing state system queries. A very
+simple implementation is available in TmfStateInterval. Its methods should be
+self-descriptive.
+
+=== Exceptions ===
+
+The following exceptions, found in o.e.l.tmf.core.exceptions, are related to
+state system activities.
+
+==== AttributeNotFoundException ====
+
+This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not byt the
+-AndAdd versions!) when passing an attribute path that is not present in the
+state system. This is to ensure that no new attribute is created when using
+these versions of the methods.
+
+Views can expect some attributes to be present, but they should handle these
+exceptions for when the attributes end up not being in the state system (perhaps
+this particular trace didn't have a certain type of events, etc.)
+
+==== StateValueTypeException ====
+
+This exception will be thrown when trying to unbox a state value into a type
+different than its own. You should always check with ITmfStateValue#getType()
+beforehand if you are not sure about the type of a given state value.
+
+==== TimeRangeException ====
+
+This exception is thrown when trying to do a query on the state system for a
+timestamp that is outside of its range. To be safe, you should check with
+ITmfStateSystem#getStartTime() and #getCurrentEndTime() for the current valid
+range of the state system. This is especially important when doing queries on
+a state system that is currently being built.
+
+==== StateSystemDisposedException ====
+
+This exception is thrown when trying to access a state system that has been
+disposed, with its dispose() method. This can potentially happen at shutdown,
+since Eclipse is not always consistent with the order in which the components
+are closed.
+
+
+== Comparison of state system backends ==
+
+As we have seen in section [[#High-level components]], the state system needs
+a storage backend to save the intervals. Different implementations are
+available when building your state system from TmfStateSystemFactory.
+
+Do not confuse full/single queries with full/partial history! All backend types
+should be able to handle any type of queries defined in the ITmfStateSystem API,
+unless noted otherwise.
+
+=== Full history ===
+
+Available with TmfStateSystemFactory#newFullHistory(). The full history uses a
+History Tree data structure, which is an optimized structure store state
+intervals on disk. Once built, it can respond to queries in a ''log(n)'' manner.
+
+You need to specify a file at creation time, which will be the container for
+the history tree. Once it's completely built, it will remain on disk (until you
+delete the trace from the project). This way it can be reused from one session
+to another, which makes subsequent loading time much faster.
+
+This the backend used by the LTTng kernel plugin. It offers good scalability and
+performance, even at extreme sizes (it's been tested with traces of sizes up to
+500 GB). Its main downside is the amount of disk space required: since every
+single interval is written to disk, the size of the history file can quite
+easily reach and even surpass the size of the trace itself.
+
+=== Null history ===
+
+Available with TmfStateSystemFactory#newNullHistory(). As its name implies the
+null history is in fact an absence of state history. All its query methods will
+return null (see the Javadoc in NullBackend).
+
+Obviously, no file is required, and almost no memory space is used.
+
+It's meant to be used in cases where you are not interested in past states, but
+only in the "ongoing" one. It can also be useful for debugging and benchmarking.
+
+=== In-memory history ===
+
+Available with TmfStateSystemFactory#newInMemHistory(). This is a simple wrapper
+using a TreeSet to store all state intervals in memory. The implementation at
+the moment is quite simple, it will perform a binary search on entries when
+doing queries to find the ones that match.
+
+The advantage of this method is that it's very quick to build and query, since
+all the information resides in memory. However, you are limited to 2^31 entries
+(roughly 2 billions), and depending on your state provider and trace type, that
+can happen really fast!
+
+There are no safeguards, so if you bust the limit you will end up with
+ArrayOutOfBoundsException's everywhere. If your trace or state history can be
+arbitrarily big, it's probably safer to use a Full History instead.
+
+=== Partial history ===
+
+Available with TmfStateSystemFactory#newPartialHistory(). The partial history is
+a more advanced form of the full history. Instead of writing all state intervals
+to disk like with the full history, we only write a small fraction of them, and
+go back to read the trace to recreate the states in-between.
+
+It has a big advantage over a full history in terms of disk space usage. It's
+very possible to reduce the history tree file size by a factor of 1000, while
+keeping query times within a factor of two. Its main downside comes from the
+fact that you cannot do efficient single queries with it (they are implemented
+by doing full queries underneath).
+
+This makes it a poor choice for views like the Control Flow view, where you do
+a lot of range queries and single queries. However, it is a perfect fit for
+cases like statistics, where you usually do full queries already, and you store
+lots of small states which are very easy to "compress".
+
+However, it can't really be used until bug 409630 is fixed.
+
+== State System Operations ==
+
+TmfStateSystemOperations is a static class that implements additional
+statistical operations that can be performed on attributes of the state system.
+
+These operations require that the attribute be one of the numerical values
+(int, long or double).
+
+The speed of these operations can be greatly improved for large data sets if
+the attribute was inserted in the state system as a mipmap attribute. Refer to
+the [[#Mipmap feature | Mipmap feature]] section.
+
+===== queryRangeMax() =====
+
+This method returns the maximum numerical value of an attribute in the
+specified time range. The attribute must be of type int, long or double.
+Null values are ignored. The returned value will be of the same state value
+type as the base attribute, or a null value if there is no state interval
+stored in the given time range.
+
+===== queryRangeMin() =====
+
+This method returns the minimum numerical value of an attribute in the
+specified time range. The attribute must be of type int, long or double.
+Null values are ignored. The returned value will be of the same state value
+type as the base attribute, or a null value if there is no state interval
+stored in the given time range.
+
+===== queryRangeAverage() =====
+
+This method returns the average numerical value of an attribute in the
+specified time range. The attribute must be of type int, long or double.
+Each state interval value is weighted according to time. Null values are
+counted as zero. The returned value will be a double primitive, which will
+be zero if there is no state interval stored in the given time range.
+
+== Code example ==
+
+Here is a small example of code that will use the state system. For this
+example, let's assume we want to track the state of all the CPUs in a LTTng
+kernel trace. To do so, we will watch for the "sched_switch" event in the state
+provider, and will update an attribute indicating if the associated CPU should
+be set to "running" or "idle".
+
+We will use an attribute tree that looks like this:
+<pre>
+CPUs
+ |--0
+ | |--Status
+ |
+ |--1
+ | |--Status
+ |
+ | 2
+ | |--Status
+...
+</pre>
+
+The second-level attributes will be named from the information available in the
+trace events. Only the "Status" attributes will carry a state value (this means
+we could have just used "1", "2", "3",... directly, but we'll do it in a tree
+for the example's sake).
+
+Also, we will use integer state values to represent "running" or "idle", instead
+of saving the strings that would get repeated every time. This will help in
+reducing the size of the history file.
+
+First we will define a state provider in MyStateProvider. Then, assuming we
+have already implemented a custom trace type extending CtfTmfTrace, we will add
+a section to it to make it build a state system using the provider we defined
+earlier. Finally, we will show some example code that can query the state
+system, which would normally go in a view or analysis module.
+
+=== State Provider ===
+
+<pre>
+import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
+import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
+import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
+import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException;
+import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
+import org.eclipse.linuxtools.tmf.core.statesystem.AbstractTmfStateProvider;
+import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
+import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
+import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
+
+/**
+ * Example state system provider.
+ *
+ * @author Alexandre Montplaisir
+ */
+public class MyStateProvider extends AbstractTmfStateProvider {
+
+ /** State value representing the idle state */
+ public static ITmfStateValue IDLE = TmfStateValue.newValueInt(0);
+
+ /** State value representing the running state */
+ public static ITmfStateValue RUNNING = TmfStateValue.newValueInt(1);
+
+ /**
+ * Constructor
+ *
+ * @param trace
+ * The trace to which this state provider is associated
+ */
+ public MyStateProvider(ITmfTrace trace) {
+ super(trace, CtfTmfEvent.class, "Example"); //$NON-NLS-1$
+ /*
+ * The third parameter here is not important, it's only used to name a
+ * thread internally.
+ */
+ }
+
+ @Override
+ public int getVersion() {
+ /*
+ * If the version of an existing file doesn't match the version supplied
+ * in the provider, a rebuild of the history will be forced.
+ */
+ return 1;
+ }
+
+ @Override
+ public MyStateProvider getNewInstance() {
+ return new MyStateProvider(getTrace());
+ }
+
+ @Override
+ protected void eventHandle(ITmfEvent ev) {
+ /*
+ * AbstractStateChangeInput should have already checked for the correct
+ * class type.
+ */
+ CtfTmfEvent event = (CtfTmfEvent) ev;
+
+ final long ts = event.getTimestamp().getValue();
+ Integer nextTid = ((Long) event.getContent().getField("next_tid").getValue()).intValue();
+
+ try {
+
+ if (event.getEventName().equals("sched_switch")) {
+ int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(event.getCPU()), "Status");
+ ITmfStateValue value;
+ if (nextTid > 0) {
+ value = RUNNING;
+ } else {
+ value = IDLE;
+ }
+ ss.modifyAttribute(ts, value, quark);
+ }
+
+ } catch (TimeRangeException e) {
+ /*
+ * This should not happen, since the timestamp comes from a trace
+ * event.
+ */
+ throw new IllegalStateException(e);
+ } catch (AttributeNotFoundException e) {
+ /*
+ * This should not happen either, since we're only accessing a quark
+ * we just created.
+ */
+ throw new IllegalStateException(e);
+ } catch (StateValueTypeException e) {
+ /*
+ * This wouldn't happen here, but could potentially happen if we try
+ * to insert mismatching state value types in the same attribute.
+ */
+ e.printStackTrace();
+ }
+
+ }
+
+}
+</pre>
+
+=== Trace type definition ===
+
+<pre>
+import java.io.File;
+
+import org.eclipse.core.resources.IProject;
+import org.eclipse.core.runtime.IStatus;
+import org.eclipse.core.runtime.Status;
+import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
+import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
+import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateProvider;
+import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
+import org.eclipse.linuxtools.tmf.core.statesystem.TmfStateSystemFactory;
+import org.eclipse.linuxtools.tmf.core.trace.TmfTraceManager;
+
+/**
+ * Example of a custom trace type using a custom state provider.
+ *
+ * @author Alexandre Montplaisir
+ */
+public class MyTraceType extends CtfTmfTrace {
+
+ /** The file name of the history file */
+ public final static String HISTORY_FILE_NAME = "mystatefile.ht";
+
+ /** ID of the state system we will build */
+ public static final String STATE_ID = "org.eclipse.linuxtools.lttng2.example";
+
+ /**
+ * Default constructor
+ */
+ public MyTraceType() {
+ super();
+ }
+
+ @Override
+ public IStatus validate(final IProject project, final String path) {
+ /*
+ * Add additional validation code here, and return a IStatus.ERROR if
+ * validation fails.
+ */
+ return Status.OK_STATUS;
+ }
+
+ @Override
+ protected void buildStateSystem() throws TmfTraceException {
+ super.buildStateSystem();
+
+ /* Build the custom state system for this trace */
+ String directory = TmfTraceManager.getSupplementaryFileDir(this);
+ final File htFile = new File(directory + HISTORY_FILE_NAME);
+ final ITmfStateProvider htInput = new MyStateProvider(this);
+
+ ITmfStateSystem ss = TmfStateSystemFactory.newFullHistory(htFile, htInput, false);
+ fStateSystems.put(STATE_ID, ss);
+ }
+
+}
+</pre>
+
+=== Query code ===
+
+<pre>
+import java.util.List;
+
+import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
+import org.eclipse.linuxtools.tmf.core.exceptions.StateSystemDisposedException;
+import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
+import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
+import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
+import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
+import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
+
+/**
+ * Class showing examples of state system queries.
+ *
+ * @author Alexandre Montplaisir
+ */
+public class QueryExample {
+
+ private final ITmfStateSystem ss;
+
+ /**
+ * Constructor
+ *
+ * @param trace
+ * Trace that this "view" will display.
+ */
+ public QueryExample(ITmfTrace trace) {
+ ss = trace.getStateSystems().get(MyTraceType.STATE_ID);
+ }
+
+ /**
+ * Example method of querying one attribute in the state system.
+ *
+ * We pass it a cpu and a timestamp, and it returns us if that cpu was
+ * executing a process (true/false) at that time.
+ *
+ * @param cpu
+ * The CPU to check
+ * @param timestamp
+ * The timestamp of the query
+ * @return True if the CPU was running, false otherwise
+ */
+ public boolean cpuIsRunning(int cpu, long timestamp) {
+ try {
+ int quark = ss.getQuarkAbsolute("CPUs", String.valueOf(cpu), "Status");
+ ITmfStateValue value = ss.querySingleState(timestamp, quark).getStateValue();
+
+ if (value.equals(MyStateProvider.RUNNING)) {
+ return true;
+ }
+
+ /*
+ * Since at this level we have no guarantee on the contents of the state
+ * system, it's important to handle these cases correctly.
+ */
+ } catch (AttributeNotFoundException e) {
+ /*
+ * Handle the case where the attribute does not exist in the state
+ * system (no CPU with this number, etc.)
+ */
+ ...
+ } catch (TimeRangeException e) {
+ /*
+ * Handle the case where 'timestamp' is outside of the range of the
+ * history.
+ */
+ ...
+ } catch (StateSystemDisposedException e) {
+ /*
+ * Handle the case where the state system is being disposed. If this
+ * happens, it's normally when shutting down, so the view can just
+ * return immediately and wait it out.
+ */
+ }
+ return false;
+ }
+
+
+ /**
+ * Example method of using a full query.
+ *
+ * We pass it a timestamp, and it returns us how many CPUs were executing a
+ * process at that moment.
+ *
+ * @param timestamp
+ * The target timestamp
+ * @return The amount of CPUs that were running at that time
+ */
+ public int getNbRunningCpus(long timestamp) {
+ int count = 0;
+
+ try {
+ /* Get the list of the quarks we are interested in. */
+ List<Integer> quarks = ss.getQuarks("CPUs", "*", "Status");
+
+ /*
+ * Get the full state at our target timestamp (it's better than
+ * doing an arbitrary number of single queries).
+ */
+ List<ITmfStateInterval> state = ss.queryFullState(timestamp);
+
+ /* Look at the value of the state for each quark */
+ for (Integer quark : quarks) {
+ ITmfStateValue value = state.get(quark).getStateValue();
+ if (value.equals(MyStateProvider.RUNNING)) {
+ count++;
+ }
+ }
+
+ } catch (TimeRangeException e) {
+ /*
+ * Handle the case where 'timestamp' is outside of the range of the
+ * history.
+ */
+ ...
+ } catch (StateSystemDisposedException e) {
+ /* Handle the case where the state system is being disposed. */
+ ...
+ }
+ return count;
+ }
+}
+</pre>
+
+== Mipmap feature ==
+
+The mipmap feature allows attributes to be inserted into the state system with
+additional computations performed to automatically store sub-attributes that
+can later be used for statistical operations. The mipmap has a resolution which
+represents the number of state attribute changes that are used to compute the
+value at the next mipmap level.
+
+The supported mipmap features are: max, min, and average. Each one of these
+features requires that the base attribute be a numerical state value (int, long
+or double). An attribute can be mipmapped for one or more of the features at
+the same time.
+
+To use a mipmapped attribute in queries, call the corresponding methods of the
+static class [[#State System Operations | TmfStateSystemOperations]].
+
+=== AbstractTmfMipmapStateProvider ===
+
+AbstractTmfMipmapStateProvider is an abstract provider class that allows adding
+features to a specific attribute into a mipmap tree. It extends AbstractTmfStateProvider.
+
+If a provider wants to add mipmapped attributes to its tree, it must extend
+AbstractTmfMipmapStateProvider and call modifyMipmapAttribute() in the event
+handler, specifying one or more mipmap features to compute. Then the structure
+of the attribute tree will be :
+
+<pre>
+|- <attribute>
+| |- <mipmapFeature> (min/max/avg)
+| | |- 1
+| | |- 2
+| | |- 3
+| | ...
+| | |- n (maximum mipmap level)
+| |- <mipmapFeature> (min/max/avg)
+| | |- 1
+| | |- 2
+| | |- 3
+| | ...
+| | |- n (maximum mipmap level)
+| ...
+</pre>
+
+= UML2 Sequence Diagram Framework =
+
+The purpose of the UML2 Sequence Diagram Framework of TMF is to provide a framework for generation of UML2 sequence diagrams. It provides
+*UML2 Sequence diagram drawing capabilities (i.e. lifelines, messages, activations, object creation and deletion)
+*a generic, re-usable Sequence Diagram View
+*Eclipse Extension Point for the creation of sequence diagrams
+*callback hooks for searching and filtering within the Sequence Diagram View
+*scalability<br>
+The following chapters describe the Sequence Diagram Framework as well as a reference implementation and its usage.
+
+== TMF UML2 Sequence Diagram Extensions ==
+
+In the UML2 Sequence Diagram Framework an Eclipse extension point is defined so that other plug-ins can contribute code to create sequence diagram.
+
+'''Identifier''': org.eclipse.linuxtools.tmf.ui.uml2SDLoader<br>
+'''Since''': 1.0<br>
+'''Description''': This extension point aims to list and connect any UML2 Sequence Diagram loader.<br>
+'''Configuration Markup''':<br>
+
+<pre>
+<!ELEMENT extension (uml2SDLoader)+>
+<!ATTLIST extension
+point CDATA #REQUIRED
+id CDATA #IMPLIED
+name CDATA #IMPLIED
+>
+</pre>
+
+*point - A fully qualified identifier of the target extension point.
+*id - An optional identifier of the extension instance.
+*name - An optional name of the extension instance.
+
+<pre>
+<!ELEMENT uml2SDLoader EMPTY>
+<!ATTLIST uml2SDLoader
+id CDATA #REQUIRED
+name CDATA #REQUIRED
+class CDATA #REQUIRED
+view CDATA #REQUIRED
+default (true | false)
+</pre>
+
+*id - A unique identifier for this uml2SDLoader. This is not mandatory as long as the id attribute cannot be retrieved by the provider plug-in. The class attribute is the one on which the underlying algorithm relies.
+*name - An name of the extension instance.
+*class - The implementation of this UML2 SD viewer loader. The class must implement org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader.
+*view - The view ID of the view that this loader aims to populate. Either org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView itself or a extension of org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView.
+*default - Set to true to make this loader the default one for the view; in case of several default loaders, first one coming from extensions list is taken.
+
+
+== Management of the Extension Point ==
+
+The TMF UI plug-in is responsible for evaluating each contribution to the extension point.
+<br>
+<br>
+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]])
+
+== Sequence Diagram View ==
+
+For this extension point a Sequence Diagram View has to be defined as well. The Sequence Diagram View class implementation is provided by the plug-in ''org.eclipse.linuxtools.tmf.ui'' (''org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView'') and can be used as is or can also be sub-classed. For that, a view extension has to be added to the ''plugin.xml''.
+
+=== Supported Widgets ===
+
+The loader class provides a frame containing all the UML2 widgets to be displayed. The following widgets exist:
+
+*Lifeline
+*Activation
+*Synchronous Message
+*Asynchronous Message
+*Synchronous Message Return
+*Asynchronous Message Return
+*Stop
+
+For a lifeline, a category can be defined. The lifeline category defines icons, which are displayed in the lifeline header.
+
+=== Zooming ===
+
+The Sequence Diagram View allows the user to zoom in, zoom out and reset the zoom factor.
+
+=== Printing ===
+
+It is possible to print the whole sequence diagram as well as part of it.
+
+=== Key Bindings ===
+
+*SHIFT+ALT+ARROW-DOWN - to scroll down within sequence diagram one view page at a time
+*SHIFT+ALT+ARROW-UP - to scroll up within sequence diagram one view page at a time
+*SHIFT+ALT+ARROW-RIGHT - to scroll right within sequence diagram one view page at a time
+*SHIFT+ALT+ARROW-LEFT - to scroll left within sequence diagram one view page at a time
+*SHIFT+ALT+ARROW-HOME - to jump to the beginning of the selected message if not already visible in page
+*SHIFT+ALT+ARROW-END - to jump to the end of the selected message if not already visible in page
+*CTRL+F - to open find dialog if either the basic or extended find provider is defined (see [[#Using the Find Provider Interface | Using the Find Provider Interface]])
+*CTRL+P - to open print dialog
+
+=== Preferences ===
+
+The UML2 Sequence Diagram Framework provides preferences to customize the appearance of the Sequence Diagram View. The color of all widgets and text as well as the fonts of the text of all widget can be adjust. Amongst others the default lifeline width can be alternated. To change preferences select '''Windows->Preferences->Tracing->UML2 Sequence Diagrams'''. The following preference page will show:<br>
+[[Image:images/SeqDiagramPref.png]] <br>
+After changing the preferences select '''OK'''.
+
+=== Callback hooks ===
+
+The Sequence Diagram View provides several callback hooks so that extension can provide application specific functionality. The following interfaces can be provided:
+* Basic find provider or extended find Provider<br> For finding within the sequence diagram
+* Basic filter provider and extended Filter Provider<br> For filtering within the sequnce diagram.
+* Basic paging provider or advanced paging provider<br> For scalability reasons, used to limit number of displayed messages
+* Properies provider<br> To provide properties of selected elements
+* Collapse provider <br> To collapse areas of the sequence diagram
+
+== Tutorial ==
+
+This tutorial describes how to create a UML2 Sequence Diagram Loader extension and use this loader in the in Eclipse.
+
+=== Prerequisites ===
+
+The tutorial is based on Eclipse 4.4 (Eclipse Luna) and TMF 3.0.0.
+
+=== Creating an Eclipse UI Plug-in ===
+
+To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
+[[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
+
+[[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
+
+[[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
+
+=== Creating a Sequence Diagram View ===
+
+To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
+[[Image:images/SelectManifest.png]]<br>
+
+Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-ins ''org.eclipse.linuxtools.tmf.ui'' and ''org.eclipse.linuxtools.tmf.core'' and then press '''OK'''<br>
+[[Image:images/AddDependencyTmfUi.png]]<br>
+
+Change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the view extension ''org.eclipse.ui.views'' and press '''Finish'''.<br>
+[[Image:images/AddViewExtension1.png]]<br>
+
+To create a Sequence Diagram View, click the right mouse button. Then select '''New -> view'''<br>
+[[Image:images/AddViewExtension2.png]]<br>
+
+A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. Note that for ''class'' the SD view implementation (''org.eclipse.linuxtools.tmf.ui.views.SDView'') of the TMF UI plug-in is used.<br>
+[[Image:images/FillSampleSeqDiagram.png]]<br>
+
+The view is prepared. Run the Example. To launch the an Eclipse Application select the ''Overview'' tab and click on '''Launch an Eclipse Application'''<br>
+[[Image:images/RunEclipseApplication.png]]<br>
+
+A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample Sequence Diagram'''.<br>
+[[Image:images/ShowViewOther.png]]<br>
+
+The Sequence Diagram View will open with an blank page.<br>
+[[Image:images/BlankSampleSeqDiagram.png]]<br>
+
+Close the Example Application.
+
+=== Defining the uml2SDLoader Extension ===
+
+After defining the Sequence Diagram View it's time to create the ''uml2SDLoader'' Extension. <br>
+
+Before doing that add a dependency to TMF. For that select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf'' and press '''OK'''<br>
+[[Image:images/AddDependencyTmf.png]]<br>
+
+To create the loader extension, change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the extension ''org.eclipse.linuxtools.tmf.ui.uml2SDLoader'' and press '''Finish'''.<br>
+[[Image:images/AddTmfUml2SDLoader.png]]<br>
+
+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>
+[[Image:images/FillSampleLoader.png]]<br>
+
+Then click on ''class'' (see above) to open the new class dialog box. Fill in the relevant fields and select '''Finish'''. <br>
+[[Image:images/NewSampleLoaderClass.png]]<br>
+
+A new Java class will be created which implements the interface ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader''.<br>
+
+<pre>
+package org.eclipse.linuxtools.tmf.sample.ui;
+
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
+
+public class SampleLoader implements IUml2SDLoader {
+
+ public SampleLoader() {
+ // TODO Auto-generated constructor stub
+ }
+
+ @Override
+ public void dispose() {
+ // TODO Auto-generated method stub
+
+ }
+
+ @Override
+ public String getTitleString() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ // TODO Auto-generated method stub
+
+ }
+</pre>
+
+=== Implementing the Loader Class ===
+
+Next is to implement the methods of the IUml2SDLoader interface method. The following code snippet shows how to create the major sequence diagram elements. Please note that no time information is stored.<br>
+
+<pre>
+package org.eclipse.linuxtools.tmf.sample.ui;
+
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessage;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessageReturn;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.ExecutionOccurrence;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Frame;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Lifeline;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Stop;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessage;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessageReturn;
+import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
+
+public class SampleLoader implements IUml2SDLoader {
+
+ private SDView fSdView;
+
+ public SampleLoader() {
+ }
+
+ @Override
+ public void dispose() {
+ }
+
+ @Override
+ public String getTitleString() {
+ return "Sample Diagram";
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ fSdView = arg0;
+ createFrame();
+ }
+
+ private void createFrame() {
+
+ Frame testFrame = new Frame();
+ testFrame.setName("Sample Frame");
+
+ /*
+ * Create lifelines
+ */
+
+ Lifeline lifeLine1 = new Lifeline();
+ lifeLine1.setName("Object1");
+ testFrame.addLifeLine(lifeLine1);
+
+ Lifeline lifeLine2 = new Lifeline();
+ lifeLine2.setName("Object2");
+ testFrame.addLifeLine(lifeLine2);
+
+
+ /*
+ * Create Sync Message
+ */
+ // Get new occurrence on lifelines
+ lifeLine1.getNewEventOccurrence();
+
+ // Get Sync message instances
+ SyncMessage start = new SyncMessage();
+ start.setName("Start");
+ start.setEndLifeline(lifeLine1);
+ testFrame.addMessage(start);
+
+ /*
+ * Create Sync Message
+ */
+ // Get new occurrence on lifelines
+ lifeLine1.getNewEventOccurrence();
+ lifeLine2.getNewEventOccurrence();
+
+ // Get Sync message instances
+ SyncMessage syn1 = new SyncMessage();
+ syn1.setName("Sync Message 1");
+ syn1.setStartLifeline(lifeLine1);
+ syn1.setEndLifeline(lifeLine2);
+ testFrame.addMessage(syn1);
+
+ /*
+ * Create corresponding Sync Message Return
+ */
+
+ // Get new occurrence on lifelines
+ lifeLine1.getNewEventOccurrence();
+ lifeLine2.getNewEventOccurrence();
+
+ SyncMessageReturn synReturn1 = new SyncMessageReturn();
+ synReturn1.setName("Sync Message Return 1");
+ synReturn1.setStartLifeline(lifeLine2);
+ synReturn1.setEndLifeline(lifeLine1);
+ synReturn1.setMessage(syn1);
+ testFrame.addMessage(synReturn1);
+
+ /*
+ * Create Activations (Execution Occurrence)
+ */
+ ExecutionOccurrence occ1 = new ExecutionOccurrence();
+ occ1.setStartOccurrence(start.getEventOccurrence());
+ occ1.setEndOccurrence(synReturn1.getEventOccurrence());
+ lifeLine1.addExecution(occ1);
+ occ1.setName("Activation 1");
+
+ ExecutionOccurrence occ2 = new ExecutionOccurrence();
+ occ2.setStartOccurrence(syn1.getEventOccurrence());
+ occ2.setEndOccurrence(synReturn1.getEventOccurrence());
+ lifeLine2.addExecution(occ2);
+ occ2.setName("Activation 2");
+
+ /*
+ * Create Sync Message
+ */
+ // Get new occurrence on lifelines
+ lifeLine1.getNewEventOccurrence();
+ lifeLine2.getNewEventOccurrence();
+
+ // Get Sync message instances
+ AsyncMessage asyn1 = new AsyncMessage();
+ asyn1.setName("Async Message 1");
+ asyn1.setStartLifeline(lifeLine1);
+ asyn1.setEndLifeline(lifeLine2);
+ testFrame.addMessage(asyn1);
+
+ /*
+ * Create corresponding Sync Message Return
+ */
+
+ // Get new occurrence on lifelines
+ lifeLine1.getNewEventOccurrence();
+ lifeLine2.getNewEventOccurrence();
+
+ AsyncMessageReturn asynReturn1 = new AsyncMessageReturn();
+ asynReturn1.setName("Async Message Return 1");
+ asynReturn1.setStartLifeline(lifeLine2);
+ asynReturn1.setEndLifeline(lifeLine1);
+ asynReturn1.setMessage(asyn1);
+ testFrame.addMessage(asynReturn1);
+
+ /*
+ * Create a note
+ */
+
+ // Get new occurrence on lifelines
+ lifeLine1.getNewEventOccurrence();
+
+ EllipsisMessage info = new EllipsisMessage();
+ info.setName("Object deletion");
+ info.setStartLifeline(lifeLine2);
+ testFrame.addNode(info);
+
+ /*
+ * Create a Stop
+ */
+ Stop stop = new Stop();
+ stop.setLifeline(lifeLine2);
+ stop.setEventOccurrence(lifeLine2.getNewEventOccurrence());
+ lifeLine2.addNode(stop);
+
+ fSdView.setFrame(testFrame);
+ }
+}
+</pre>
+
+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>
+[[Image:images/SampleDiagram1.png]] <br>
+
+=== Adding time information ===
+
+To add time information in sequence diagram the timestamp has to be set for each message. The sequence diagram framework uses the ''TmfTimestamp'' class of plug-in ''org.eclipse.linuxtools.tmf.core''. Use ''setTime()'' on each message ''SyncMessage'' since start and end time are the same. For each ''AsyncMessage'' set start and end time separately by using methods ''setStartTime'' and ''setEndTime''. For example: <br>
+
+<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));
+ //...
+ }
+</pre>
+
+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>
+
+[[Image:images/SampleDiagramTimeComp.png]] <br>
+
+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.
+
+[[Image:images/SampleDiagramSyncMessage.png]] <br>
+[[Image:images/SampleDiagramAsyncMessage.png]] <br>
+
+To see the time elapsed between 2 messages, select one message and hover over a second message. A tooltip will show with the delta in time. Note if the second message is before the first then a negative delta is displayed. Note that for ''AsyncMessage'' the end time is used for the delta calculation.<br>
+[[Image:images/SampleDiagramMessageDelta.png]] <br>
+
+=== Default Coolbar and Menu Items ===
+
+The Sequence Diagram View comes with default coolbar and menu items. By default, each sequence diagram shows the following actions:
+* Zoom in
+* Zoom out
+* Reset Zoom Factor
+* Selection
+* Configure Min Max (drop-down menu only)
+* Navigation -> Show the node end (drop-down menu only)
+* Navigation -> Show the node start (drop-down menu only)
+
+[[Image:images/DefaultCoolbarMenu.png]]<br>
+
+=== Implementing Optional Callbacks ===
+
+The following chapters describe how to use all supported provider interfaces.
+
+==== Using the Paging Provider Interface ====
+
+For scalability reasons, the paging provider interfaces exists to limit the number of messages displayed in the Sequence Diagram View at a time. For that, two interfaces exist, the basic paging provider and the advanced paging provider. When using the basic paging interface, actions for traversing page by page through the sequence diagram of a trace will be provided.
+<br>
+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.
+
+<pre>
+public class SampleLoader implements IUml2SDLoader, ISDPagingProvider {
+ //...
+ private page = 0;
+
+ @Override
+ public void dispose() {
+ if (fSdView != null) {
+ fSdView.resetProviders();
+ }
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ fSdView = arg0;
+ fSdView.setSDPagingProvider(this);
+ createFrame();
+ }
+
+ private void createSecondFrame() {
+ Frame testFrame = new Frame();
+ testFrame.setName("SecondFrame");
+ Lifeline lifeline = new Lifeline();
+ lifeline.setName("LifeLine 0");
+ testFrame.addLifeLine(lifeline);
+ lifeline = new Lifeline();
+ lifeline.setName("LifeLine 1");
+ testFrame.addLifeLine(lifeline);
+ for (int i = 1; i < 5; i++) {
+ SyncMessage message = new SyncMessage();
+ message.autoSetStartLifeline(testFrame.getLifeline(0));
+ message.autoSetEndLifeline(testFrame.getLifeline(0));
+ message.setName((new StringBuilder("Message ")).append(i).toString());
+ testFrame.addMessage(message);
+
+ SyncMessageReturn messageReturn = new SyncMessageReturn();
+ messageReturn.autoSetStartLifeline(testFrame.getLifeline(0));
+ messageReturn.autoSetEndLifeline(testFrame.getLifeline(0));
+
+ testFrame.addMessage(messageReturn);
+ messageReturn.setName((new StringBuilder("Message return ")).append(i).toString());
+ ExecutionOccurrence occ = new ExecutionOccurrence();
+ occ.setStartOccurrence(testFrame.getSyncMessage(i - 1).getEventOccurrence());
+ occ.setEndOccurrence(testFrame.getSyncMessageReturn(i - 1).getEventOccurrence());
+ testFrame.getLifeline(0).addExecution(occ);
+ }
+ fSdView.setFrame(testFrame);
+ }
+
+ @Override
+ public boolean hasNextPage() {
+ return page == 0;
+ }
+
+ @Override
+ public boolean hasPrevPage() {
+ return page == 1;
+ }
+
+ @Override
+ public void nextPage() {
+ page = 1;
+ createSecondFrame();
+ }
+
+ @Override
+ public void prevPage() {
+ page = 0;
+ createFrame();
+ }
+
+ @Override
+ public void firstPage() {
+ page = 0;
+ createFrame();
+ }
+
+ @Override
+ public void lastPage() {
+ page = 1;
+ createSecondFrame();
+ }
+ //...
+}
+
+</pre>
+
+When running the example application, new actions will be shown in the coolbar and the coolbar menu. <br>
+
+[[Image:images/PageProviderAdded.png]]
+
+<br><br>
+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.
+<br>
+
+==== Using the Find Provider Interface ====
+
+For finding nodes in a sequence diagram two interfaces exists. One for basic finding and one for extended finding. The basic find comes with a dialog box for entering find criteria as regular expressions. This find criteria can be used to execute the find. Find criteria a persisted in the Eclipse workspace.
+<br>
+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.
+<br>
+Only on at a time can be active. If the extended find provder is defined it obsoletes the basic find provider.
+<br>
+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.
+
+<pre>
+public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider {
+
+ //...
+ @Override
+ public void dispose() {
+ if (fSdView != null) {
+ fSdView.resetProviders();
+ }
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ fSdView = arg0;
+ fSdView.setSDPagingProvider(this);
+ fSdView.setSDFindProvider(this);
+ createFrame();
+ }
+
+ @Override
+ public boolean isNodeSupported(int nodeType) {
+ switch (nodeType) {
+ case ISDGraphNodeSupporter.LIFELINE:
+ case ISDGraphNodeSupporter.SYNCMESSAGE:
+ return true;
+
+ default:
+ break;
+ }
+ return false;
+ }
+
+ @Override
+ public String getNodeName(int nodeType, String loaderClassName) {
+ switch (nodeType) {
+ case ISDGraphNodeSupporter.LIFELINE:
+ return "Lifeline";
+ case ISDGraphNodeSupporter.SYNCMESSAGE:
+ return "Sync Message";
+ }
+ return "";
+ }
+
+ @Override
+ public boolean find(Criteria criteria) {
+ Frame frame = fSdView.getFrame();
+ if (criteria.isLifeLineSelected()) {
+ for (int i = 0; i < frame.lifeLinesCount(); i++) {
+ if (criteria.matches(frame.getLifeline(i).getName())) {
+ fSdView.getSDWidget().moveTo(frame.getLifeline(i));
+ return true;
+ }
+ }
+ }
+ if (criteria.isSyncMessageSelected()) {
+ for (int i = 0; i < frame.syncMessageCount(); i++) {
+ if (criteria.matches(frame.getSyncMessage(i).getName())) {
+ fSdView.getSDWidget().moveTo(frame.getSyncMessage(i));
+ return true;
+ }
+ }
+ }
+ return false;
+ }
+
+ @Override
+ public void cancel() {
+ // reset find parameters
+ }
+ //...
+}
+</pre>
+
+When running the example application, the find action will be shown in the coolbar and the coolbar menu. <br>
+[[Image:images/FindProviderAdded.png]]
+
+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>
+[[Image:images/FindDialog.png]]<br>
+
+Note that the find dialog will be opened by typing the key shortcut CRTL+F.
+
+==== Using the Filter Provider Interface ====
+
+For filtering of sequence diagram elements two interfaces exist. One basic for filtering and one for extended filtering. The basic filtering comes with two dialog for entering filter criteria as regular expressions and one for selecting the filter to be used. Multiple filters can be active at a time. Filter criteria are persisted in the Eclipse workspace.
+<br>
+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>
+Note that no example implementation of ''filter()'' is provided.
+<br>
+
+<pre>
+public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider {
+
+ //...
+ @Override
+ public void dispose() {
+ if (fSdView != null) {
+ fSdView.resetProviders();
+ }
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ fSdView = arg0;
+ fSdView.setSDPagingProvider(this);
+ fSdView.setSDFindProvider(this);
+ fSdView.setSDFilterProvider(this);
+ createFrame();
+ }
+
+ @Override
+ public boolean filter(List<?> list) {
+ return false;
+ }
+ //...
+}
+</pre>
+
+When running the example application, the filter action will be shown in the coolbar menu. <br>
+[[Image:images/HidePatternsMenuItem.png]]
+
+To filter select the '''Hide Patterns...''' of the coolbar menu. A new dialog box will open. <br>
+[[Image:images/DialogHidePatterns.png]]
+
+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>
+[[Image:images/DialogHidePatterns.png]] <br>
+
+Now back at the Hide Pattern dialog. Select one or more filter and select '''OK'''.
+
+To use the extended filter provider, the interface ''ISDExtendedFilterProvider'' has to be implemented. It will provide a ''org.eclipse.jface.action.Action'' class containing the actual filter handling and filter algorithm.
+
+==== Using the Extended Action Bar Provider Interface ====
+
+The extended action bar provider can be used to add customized actions to the Sequence Diagram View.
+To use the extended action bar provider, first the interface method of the interface ''ISDExtendedActionBarProvider'' has to be implemented by a class. Typically, this is implemented in the loader class. Add the ''ISDExtendedActionBarProvider'' to the list of implemented interfaces, implement the method ''supplementCoolbarContent()'' and set the provider in the ''setViewer()'' method as well as remove the provider in the ''dispose()'' method of the loader class. <br>
+
+<pre>
+public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider {
+ //...
+
+ @Override
+ public void dispose() {
+ if (fSdView != null) {
+ fSdView.resetProviders();
+ }
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ fSdView = arg0;
+ fSdView.setSDPagingProvider(this);
+ fSdView.setSDFindProvider(this);
+ fSdView.setSDFilterProvider(this);
+ fSdView.setSDExtendedActionBarProvider(this);
+ createFrame();
+ }
+
+ @Override
+ public void supplementCoolbarContent(IActionBars iactionbars) {
+ Action action = new Action("Refresh") {
+ @Override
+ public void run() {
+ System.out.println("Refreshing...");
+ }
+ };
+ iactionbars.getMenuManager().add(action);
+ iactionbars.getToolBarManager().add(action);
+ }
+ //...
+}
+</pre>
+
+When running the example application, all new actions will be added to the coolbar and coolbar menu according to the implementation of ''supplementCoolbarContent()''<br>.
+For the example above the coolbar and coolbar menu will look as follows.
+
+[[Image:images/SupplCoolbar.png]]
+
+==== Using the Properties Provider Interface====
+
+This interface can be used to provide property information. A property provider which returns an ''IPropertyPageSheet'' (see ''org.eclipse.ui.views'') has to be implemented and set in the Sequence Diagram View. <br>
+
+To use the property provider, first the interface method of the ''ISDPropertiesProvider'' has to be implemented by a class. Typically, this is implemented in the loader class. Add the ''ISDPropertiesProvider'' to the list of implemented interfaces, implement the method ''getPropertySheetEntry()'' and set the provider in the ''setViewer()'' method as well as remove the provider in the ''dispose()'' method of the loader class. Please note that no example is provided here.
+
+Please refer to the following Eclipse articles for more information about properties and tabed properties.
+*[http://www.eclipse.org/articles/Article-Properties-View/properties-view.html | Take control of your properties]
+*[http://www.eclipse.org/articles/Article-Tabbed-Properties/tabbed_properties_view.html | The Eclipse Tabbed Properties View]
+
+==== Using the Collapse Provider Interface ====
+
+This interface can be used to define a provider which responsibility is to collapse two selected lifelines. This can be used to hide a pair of lifelines.
+
+To use the collapse provider, first the interface method of the ''ISDCollapseProvider'' has to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDCollapseProvider to the list of implemented interfaces, implement the method ''collapseTwoLifelines()'' and set the provider in the ''setViewer()'' method as well as remove the provider in the ''dispose()'' method of the loader class. Please note that no example is provided here.
+
+==== Using the Selection Provider Service ====
+
+The Sequence Diagram View comes with a build in selection provider service. To this service listeners can be added. To use the selection provider service, the interface ''ISelectionListener'' of plug-in ''org.eclipse.ui'' has to implemented. Typically this is implemented in loader class. Firstly, add the ''ISelectionListener'' interface to the list of implemented interfaces, implement the method ''selectionChanged()'' and set the listener in method ''setViewer()'' as well as remove the listener in the ''dispose()'' method of the loader class.
+
+<pre>
+public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider, ISelectionListener {
+
+ //...
+ @Override
+ public void dispose() {
+ if (fSdView != null) {
+ PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().removePostSelectionListener(this);
+ fSdView.resetProviders();
+ }
+ }
+
+ @Override
+ public String getTitleString() {
+ return "Sample Diagram";
+ }
+
+ @Override
+ public void setViewer(SDView arg0) {
+ fSdView = arg0;
+ PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().addPostSelectionListener(this);
+ fSdView.setSDPagingProvider(this);
+ fSdView.setSDFindProvider(this);
+ fSdView.setSDFilterProvider(this);
+ fSdView.setSDExtendedActionBarProvider(this);
+
+ createFrame();
+ }
+
+ @Override
+ public void selectionChanged(IWorkbenchPart part, ISelection selection) {
+ ISelection sel = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().getSelection();
+ if (sel != null && (sel instanceof StructuredSelection)) {
+ StructuredSelection stSel = (StructuredSelection) sel;
+ if (stSel.getFirstElement() instanceof BaseMessage) {
+ BaseMessage syncMsg = ((BaseMessage) stSel.getFirstElement());
+ System.out.println("Message '" + syncMsg.getName() + "' selected.");
+ }
+ }
+ }
+
+ //...
+}
+</pre>
+
+=== Printing a Sequence Diagram ===
+
+To print a the whole sequence diagram or only parts of it, select the Sequence Diagram View and select '''File -> Print...''' or type the key combination ''CTRL+P''. A new print dialog will open. <br>
+
+[[Image:images/PrintDialog.png]] <br>
+
+Fill in all the relevant information, select '''Printer...''' to choose the printer and the press '''OK'''.
+
+=== Using one Sequence Diagram View with Multiple Loaders ===
+
+A Sequence Diagram View definition can be used with multiple sequence diagram loaders. However, the active loader to be used when opening the view has to be set. For this define an Eclipse action or command and assign the current loader to the view. Here is a code snippet for that:
+
+<pre>
+public class OpenSDView extends AbstractHandler {
+ @Override
+ public Object execute(ExecutionEvent event) throws ExecutionException {
+ try {
+ IWorkbenchPage persp = TmfUiPlugin.getDefault().getWorkbench().getActiveWorkbenchWindow().getActivePage();
+ SDView view = (SDView) persp.showView("org.eclipse.linuxtools.ust.examples.ui.componentinteraction");
+ LoadersManager.getLoadersManager().createLoader("org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl.TmfUml2SDSyncLoader", view);
+ } catch (PartInitException e) {
+ throw new ExecutionException("PartInitException caught: ", e);
+ }
+ return null;
+ }
+}
+</pre>
+
+=== Downloading the Tutorial ===
+
+Use the following link to download the source code of the tutorial [http://wiki.eclipse.org/images/e/e6/SamplePlugin.zip Plug-in of Tutorial].
+
+== Integration of Tracing and Monitoring Framework with Sequence Diagram Framework ==
+
+In the previous sections the Sequence Diagram Framework has been described and a tutorial was provided. In the following sections the integration of the Sequence Diagram Framework with other features of TMF will be described. Together it is a powerful framework to analyze and visualize content of traces. The integration is explained using the reference implementation of a UML2 sequence diagram loader which part of the TMF UI delivery. The reference implementation can be used as is, can be sub-classed or simply be an example for other sequence diagram loaders to be implemented.
+
+=== Reference Implementation ===
+
+A Sequence Diagram View Extension is defined in the plug-in TMF UI as well as a uml2SDLoader Extension with the reference loader.
+
+[[Image:images/ReferenceExtensions.png]]
+
+=== Used Sequence Diagram Features ===
+
+Besides the default features of the Sequence Diagram Framework, the reference implementation uses the following additional features:
+*Advanced paging
+*Basic finding
+*Basic filtering
+*Selection Service
+
+==== Advanced paging ====
+
+The reference loader implements the interface ''ISDAdvancedPagingProvider'' interface. Please refer to section [[#Using the Paging Provider Interface | Using the Paging Provider Interface]] for more details about the advanced paging feature.
+
+==== Basic finding ====
+
+The reference loader implements the interface ''ISDFindProvider'' interface. The user can search for ''Lifelines'' and ''Interactions''. The find is done across pages. If the expression to match is not on the current page a new thread is started to search on other pages. If expression is found the corresponding page is shown as well as the searched item is displayed. If not found then a message is displayed in the ''Progress View'' of Eclipse. Please refer to section [[#Using the Find Provider Interface | Using the Find Provider Interface]] for more details about the basic find feature.
+
+==== Basic filtering ====
+
+The reference loader implements the interface ''ISDFilterProvider'' interface. The user can filter on ''Lifelines'' and ''Interactions''. Please refer to section [[#Using the Filter Provider Interface | Using the Filter Provider Interface]] for more details about the basic filter feature.
+
+==== Selection Service ====
+
+The reference loader implements the interface ''ISelectionListener'' interface. When an interaction is selected a ''TmfTimeSynchSignal'' is broadcast (see [[#TMF Signal Framework | 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 .
+
+=== Used TMF Features ===
+
+The reference implementation uses the following features of TMF:
+*TMF Experiment and Trace for accessing traces
+*Event Request Framework to request TMF events from the experiment and respective traces
+*Signal Framework for broadcasting and receiving TMF signals for synchronization purposes
+
+==== TMF Experiment and Trace for accessing traces ====
+
+The reference loader uses TMF Experiments to access traces and to request data from the traces.
+
+==== TMF Event Request Framework ====
+
+The reference loader use the TMF Event Request Framework to request events from the experiment and its traces.
+
+When opening a traces (which is triggered by signal ''TmfExperimentSelected'') or when opening the Sequence Diagram View after a trace had been opened previously, a TMF background request is initiated to index the trace and to fill in the first page of the sequence diagram. The purpose of the indexing is to store time ranges for pages with 10000 messages per page. This allows quickly to move to certain pages in a trace without having to re-parse from the beginning. The request is called indexing request.
+
+When switching pages, the a TMF foreground event request is initiated to retrieve the corresponding events from the experiment. It uses the time range stored in the index for the respective page.
+
+A third type of event request is issued for finding specific data across pages.
+
+==== TMF Signal Framework ====
+
+The reference loader extends the class ''TmfComponent''. By doing that the loader is registered as a TMF signal handler for sending and receiving TMF signals. The loader implements signal handlers for the following TMF signals:
+*''TmfTraceSelectedSignal''
+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.
+*''TmfTraceClosedSignal''
+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.
+*''TmfTimeSynchSignal''
+This signal is used to indicate that a new time or time range has been selected. It contains a begin and end time. If a single time is selected then the begin and end time are the same. When receiving this signal the corresponding message matching the begin time is selected in the Sequence Diagram View. If necessary, the page is changed.
+*''TmfRangeSynchSignal''
+This signal indicates that a new time range is in focus. When receiving this signal the loader loads the page which corresponds to the start time of the time range signal. The message with the start time will be in focus.
+
+Besides acting on receiving signals, the reference loader is also sending signals. A ''TmfTimeSynchSignal'' is broadcasted with the 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''.
+
+=== Supported Traces ===
+
+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>
+
+Note that combined traces of multiple components, that contain the trace information about the same interactions are not supported in the reference implementation!
+
+=== Trace Format ===
+
+The reference implementation in class ''TmfUml2SDSyncLoader'' in package ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl'' analyzes events from type ''ITmfEvent'' and creates events type ''ITmfSyncSequenceDiagramEvent'' if the ''ITmfEvent'' contains all relevant information information. The parsing algorithm looks like as follows:
+
+<pre>
+ /**
+ * @param tmfEvent Event to parse for sequence diagram event details
+ * @return sequence diagram event if details are available else null
+ */
+ protected ITmfSyncSequenceDiagramEvent getSequenceDiagramEvent(ITmfEvent tmfEvent){
+ //type = .*RECEIVE.* or .*SEND.*
+ //content = sender:<sender name>:receiver:<receiver name>,signal:<signal name>
+ String eventType = tmfEvent.getType().toString();
+ if (eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeSend) || eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeReceive)) {
+ Object sender = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSender);
+ Object receiver = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldReceiver);
+ Object name = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSignal);
+ if ((sender instanceof ITmfEventField) && (receiver instanceof ITmfEventField) && (name instanceof ITmfEventField)) {
+ ITmfSyncSequenceDiagramEvent sdEvent = new TmfSyncSequenceDiagramEvent(tmfEvent,
+ ((ITmfEventField) sender).getValue().toString(),
+ ((ITmfEventField) receiver).getValue().toString(),
+ ((ITmfEventField) name).getValue().toString());
+
+ return sdEvent;
+ }
+ }
+ return null;
+ }
+</pre>
+
+The analysis looks for event type Strings containing ''SEND'' and ''RECEIVE''. If event type matches these key words, the analyzer will look for strings ''sender'', ''receiver'' and ''signal'' in the event fields of type ''ITmfEventField''. If all the data is found a sequence diagram event can be created using this information. Note that Sync Messages are assumed, which means start and end time are the same.
+
+=== How to use the Reference Implementation ===
+
+An example CTF (Common Trace Format) trace is provided that contains trace events with sequence diagram information. To download the reference trace, use the following link: [https://wiki.eclipse.org/images/3/35/ReferenceTrace.zip Reference Trace].
+
+Run an Eclipse application with TMF 3.0 or later installed. To open the Reference Sequence Diagram View, select '''Windows -> Show View -> Other... -> TMF -> Sequence Diagram''' <br>
+[[Image:images/ShowTmfSDView.png]]<br>
+
+A blank Sequence Diagram View will open.
+
+Then import the reference trace to the '''Project Explorer''' using the '''Import Trace Package...''' menu option.<br>
+[[Image:images/ImportTracePackage.png]]
+
+Next, open the trace by double-clicking on the trace element in the '''Project Explorer'''. The trace will be opened and the Sequence Diagram view will be filled.
+[[Image:images/ReferenceSeqDiagram.png]]<br>
+
+Now the reference implementation can be explored. To demonstrate the view features try the following things:
+*Select a message in the Sequence diagram. As result the corresponding event will be selected in the Events View.
+*Select an event in the Events View. As result the corresponding message in the Sequence Diagram View will be selected. If necessary, the page will be changed.
+*In the Events View, press key ''End''. As result, the Sequence Diagram view will jump to the last page.
+*In the Events View, press key ''Home''. As result, the Sequence Diagram view will jump to the first page.
+*In the Sequence Diagram View select the find button. Enter the expression '''REGISTER.*''', select '''Search for Interaction''' and press '''Find'''. As result the corresponding message will be selected in the Sequence Diagram and the corresponding event in the Events View will be selected. Select again '''Find''' the next occurrence of will be selected. Since the second occurrence is on a different page than the first, the corresponding page will be loaded.
+* In the Sequence Diagram View, select menu item '''Hide Patterns...'''. Add the filter '''BALL.*''' for '''Interaction''' only and select '''OK'''. As result all messages with name ''BALL_REQUEST'' and ''BALL_REPLY'' will be hidden. To remove the filter, select menu item '''Hide Patterns...''', deselect the corresponding filter and press '''OK'''. All the messages will be shown again.<br>
+
+=== Extending the Reference Loader ===
+
+In some case it might be necessary to change the implementation of the analysis of each ''TmfEvent'' for the generation of ''Sequence Diagram Events''. For that just extend the class ''TmfUml2SDSyncLoader'' and overwrite the method ''protected ITmfSyncSequenceDiagramEvent getSequnceDiagramEvent(TmfEvent tmfEvent)'' with your own implementation.
+
+= CTF Parser =
+
+== CTF Format ==
+CTF is a format used to store traces. It is self defining, binary and made to be easy to write to.
+Before going further, the full specification of the CTF file format can be found at http://www.efficios.com/ .
+
+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.
+
+These files can be split into two types :
+* Metadata
+* Event streams
+
+=== Metadata ===
+The metadata is either raw text or packetized text. It is tsdl encoded. it contains a description of the type of data in the event streams. It can grow over time if new events are added to a trace but it will never overwrite what is already there.
+
+=== Event Streams ===
+The event streams are a file per stream per cpu. These streams are binary and packet based. The streams store events and event information (ie lost events) The event data is stored in headers and field payloads.
+
+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"
+
+== Reading a trace ==
+In order to read a CTF trace, two steps must be done.
+* The metadata must be read to know how to read the events.
+* the events must be read.
+
+The metadata is a written in a subset of the C language called TSDL. To read it, first it is depacketized (if it is not in plain text) then the raw text is parsed by an antlr grammer. The parsing is done in two phases. There is a lexer (CTFLexer.g) which separated the metatdata text into tokens. The tokens are then pattern matched using the parser (CTFParser.g) to form an AST. This AST is walked through using "IOStructGen.java" to populate streams and traces in trace parent object.
+
+When the metadata is loaded and read, the trace object will be populated with 3 items:
+* the event definitions available per stream: a definition is a description of the datatype.
+* the event declarations available per stream: this will save declaration creation on a per event basis. They will all be created in advance, just not populated.
+* the beginning of a packet index.
+
+Now all the trace readers for the event streams have everything they need to read a trace. They will each point to one file, and read the file from packet to packet. Everytime the trace reader changes packet, the index is updated with the new packet's information. The readers are in a priority queue and sorted by timestamp. This ensures that the events are read in a sequential order. They are also sorted by file name so that in the eventuality that two events occur at the same time, they stay in the same order.
+
+== Seeking in a trace ==
+The reason for maintaining an index is to speed up seeks. In the case that a user wishes to seek to a certain timestamp, they just have to find the index entry that contains the timestamp, and go there to iterate in that packet until the proper event is found. this will reduce the searches time by an order of 8000 for a 256k paket size (kernel default).
+
+== Interfacing to TMF ==
+The trace can be read easily now but the data is still awkward to extract.
+
+=== CtfLocation ===
+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.
+
+=== CtfTmfTrace ===
+The CtfTmfTrace is a wrapper for the standard CTF trace that allows it to perform the following actions:
+* '''initTrace()''' create a trace
+* '''validateTrace()''' is the trace a CTF trace?
+* '''getLocationRatio()''' how far in the trace is my location?
+* '''seekEvent()''' sets the cursor to a certain point in a trace.
+* '''readNextEvent()''' reads the next event and then advances the cursor
+* '''getTraceProperties()''' gets the 'env' structures of the metadata
+
+=== CtfIterator ===
+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.
+
+=== CtfIteratorManager ===
+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.
+
+=== CtfTmfContext ===
+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.
+
+=== CtfTmfTimestamp ===
+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.
+
+=== CtfTmfEvent ===
+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.
+
+=== Other ===
+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.
+
+= Event matching and trace synchronization =
+
+Event matching consists in taking an event from a trace and linking it to another event in a possibly different trace. The example that comes to mind is matching network packets sent from one traced machine to another traced machine. These matches can be used to synchronize traces.
+
+Trace synchronization consists in taking traces, taken on different machines, with a different time reference, and finding the formula to transform the timestamps of some of the traces, so that they all have the same time reference.
+
+== Event matching interfaces ==
+
+Here's a description of the major parts involved in event matching. These classes are all in the ''org.eclipse.linuxtools.tmf.core.event.matching'' package:
+
+* '''ITmfEventMatching''': Controls the event matching process
+* '''ITmfMatchEventDefinition''': Describes how events are matched
+* '''IMatchProcessingUnit''': Processes the matched events
+
+== Implementation details and how to extend it ==
+
+=== ITmfEventMatching interface and derived classes ===
+
+This interface and its default abstract implementation '''TmfEventMatching''' control the event matching itself. Their only public method is ''matchEvents''. The class needs to manage how to setup the traces, and any initialization or finalization procedures.
+
+The abstract class generates an event request for each trace from which events are matched and waits for the request to complete before calling the one from another trace. The ''handleData'' method from the request calls the ''matchEvent'' method that needs to be implemented in children classes.
+
+Class '''TmfNetworkEventMatching''' is a concrete implementation of this interface. It applies to all use cases where a ''in'' event can be matched with a ''out' event (''in'' and ''out'' can be the same event, with different data). It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
+
+To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to implement another class either extending '''TmfEventMatching''' or implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
+
+=== ITmfMatchEventDefinition interface and its derived classes ===
+
+These are the classes that describe how to actually match specific events together.
+
+The '''canMatchTrace''' method will tell if a definition is compatible with a given trace.
+
+The '''getUniqueField''' method will return a list of field values that uniquely identify this event and can be used to find a previous event to match with.
+
+Typically, there would be a match definition abstract class/interface per event matching type.
+
+The interface '''ITmfNetworkMatchDefinition''' adds the ''getDirection'' method to indicate whether this event is a ''in'' or ''out'' event to be matched with one from the opposite direction.
+
+As examples, two concrete network match definitions have been implemented in the ''org.eclipse.linuxtools.lttng2.kernel.core.event.matching'' package for two compatible methods of matching TCP packets (See the LTTng User Guide on ''trace synchronization'' for information on those matching methods). Each one tells which events need to be present in the metadata of a CTF trace for this matching method to be applicable. It also returns the field values from each event that will uniquely match 2 events together.
+
+=== IMatchProcessingUnit interface and derived classes ===
+
+While matching events is an exercice in itself, it's what to do with the match that really makes this functionality interesting. This is the job of the '''IMatchProcessingUnit''' interface.
+
+'''TmfEventMatches''' provides a default implementation that only stores the matches to count them. When a new match is obtained, the ''addMatch'' is called with the match and the processing unit can do whatever needs to be done with it.
+
+A match processing unit can be an analysis in itself. For example, trace synchronization is done through such a processing unit. One just needs to set the processing unit in the TmfEventMatching constructor.
+
+== Code examples ==
+
+=== Using network packets matching in an analysis ===
+
+This example shows how one can create a processing unit inline to create a link between two events. In this example, the code already uses an event request, so there is no need here to call the ''matchEvents'' method, that will only create another request.
+
+<pre>
+class MyAnalysis extends TmfAbstractAnalysisModule {
+
+ private TmfNetworkEventMatching tcpMatching;
+
+ ...
+
+ protected void executeAnalysis() {
+
+ IMatchProcessingUnit matchProcessing = new IMatchProcessingUnit() {
+ @Override
+ public void matchingEnded() {
+ }
+
+ @Override
+ public void init(ITmfTrace[] fTraces) {
+ }
+
+ @Override
+ public int countMatches() {
+ return 0;
+ }
+
+ @Override
+ public void addMatch(TmfEventDependency match) {
+ log.debug("we got a tcp match! " + match.getSourceEvent().getContent() + " " + match.getDestinationEvent().getContent());
+ TmfEvent source = match.getSourceEvent();
+ TmfEvent destination = match.getDestinationEvent();
+ /* Create a link between the two events */
+ }
+ };
+
+ ITmfTrace[] traces = { getTrace() };
+ tcpMatching = new TmfNetworkEventMatching(traces, matchProcessing);
+ tcpMatching.initMatching();
+
+ MyEventRequest request = new MyEventRequest(this, i);
+ getTrace().sendRequest(request);
+ }
+
+ public void analyzeEvent(TmfEvent event) {
+ ...
+ tcpMatching.matchEvent(event, 0);
+ ...
+ }
+
+ ...
+
+}
+
+class MyEventRequest extends TmfEventRequest {
+
+ private final MyAnalysis analysis;
+
+ MyEventRequest(MyAnalysis analysis, int traceno) {
+ super(CtfTmfEvent.class,
+ TmfTimeRange.ETERNITY,
+ 0,
+ TmfDataRequest.ALL_DATA,
+ ITmfDataRequest.ExecutionType.FOREGROUND);
+ this.analysis = analysis;
+ }
+
+ @Override
+ public void handleData(final ITmfEvent event) {
+ super.handleData(event);
+ if (event != null) {
+ analysis.analyzeEvent(event);
+ }
+ }
+}
+</pre>
+
+=== Match network events from UST traces ===
+
+Suppose a client-server application is instrumented using LTTng-UST. Traces are collected on the server and some clients on different machines. The traces can be synchronized using network event matching.
+
+The following metadata describes the events:
+
+<pre>
+ event {
+ name = "myapp:send";
+ id = 0;
+ stream_id = 0;
+ loglevel = 13;
+ fields := struct {
+ integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _sendto;
+ integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _messageid;
+ integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _data;
+ };
+ };
+
+ event {
+ name = "myapp:receive";
+ id = 1;
+ stream_id = 0;
+ loglevel = 13;
+ fields := struct {
+ integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _from;
+ integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _messageid;
+ integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _data;
+ };
+ };
+</pre>
+
+One would need to write an event match definition for those 2 events as follows:
+
+<pre>
+public class MyAppUstEventMatching implements ITmfNetworkMatchDefinition {
+
+ @Override
+ public Direction getDirection(ITmfEvent event) {
+ String evname = event.getType().getName();
+ if (evname.equals("myapp:receive")) {
+ return Direction.IN;
+ } else if (evname.equals("myapp:send")) {
+ return Direction.OUT;
+ }
+ return null;
+ }
+
+ @Override
+ public List<Object> getUniqueField(ITmfEvent event) {
+ List<Object> keys = new ArrayList<Object>();
+
+ if (evname.equals("myapp:receive")) {
+ keys.add(event.getContent().getField("from").getValue());
+ keys.add(event.getContent().getField("messageid").getValue());
+ } else {
+ keys.add(event.getContent().getField("sendto").getValue());
+ keys.add(event.getContent().getField("messageid").getValue());
+ }
+
+ return keys;
+ }
+
+ @Override
+ public boolean canMatchTrace(ITmfTrace trace) {
+ if (!(trace instanceof CtfTmfTrace)) {
+ return false;
+ }
+ CtfTmfTrace ktrace = (CtfTmfTrace) trace;
+ String[] events = { "myapp:receive", "myapp:send" };
+ return ktrace.hasAtLeastOneOfEvents(events);
+ }
+
+ @Override
+ public MatchingType[] getApplicableMatchingTypes() {
+ MatchingType[] types = { MatchingType.NETWORK };
+ return types;
+ }
+
+}
+</pre>
+
+Somewhere in code that will be executed at the start of the plugin (like in the Activator), the following code will have to be run:
+
+<pre>
+TmfEventMatching.registerMatchObject(new MyAppUstEventMatching());
+</pre>
+
+Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu element would synchronize the traces using the new definition for event matching.
+
+== Trace synchronization ==
+
+Trace synchronization classes and interfaces are located in the ''org.eclipse.linuxtools.tmf.core.synchronization'' package.
+
+=== Synchronization algorithm ===
+
+Synchronization algorithms are used to synchronize traces from events matched between traces. After synchronization, traces taken on different machines with different time references see their timestamps modified such that they all use the same time reference (typically, the time of at least one of the traces). With traces from different machines, it is impossible to have perfect synchronization, so the result is a best approximation that takes network latency into account.
+
+The abstract class '''SynchronizationAlgorithm''' is a processing unit for matches. New synchronization algorithms must extend this one, it already contains the functions to get the timestamp transforms for different traces.
+
+The ''fully incremental convex hull'' synchronization algorithm is the default synchronization algorithm.
+
+While the synchronization system provisions for more synchronization algorithms, there is not yet a way to select one, the experiment's trace synchronization uses the default algorithm. To test a new synchronization algorithm, the synchronization should be called directly like this:
+
+<pre>
+SynchronizationAlgorithm syncAlgo = new MyNewSynchronizationAlgorithm();
+syncAlgo = SynchronizationManager.synchronizeTraces(syncFile, traces, syncAlgo, true);
+</pre>
+
+=== Timestamp transforms ===
+
+Timestamp transforms are the formulae used to transform the timestamps from a trace into the reference time. The '''ITmfTimestampTransform''' is the interface to implement to add a new transform.
+
+The following classes implement this interface:
+
+* '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object TmfTimestampTransform.IDENTITY, which returns the original timestamp.
+* '''TmfTimestampTransformLinear''': transforms the timestamp using a linear formula: ''f(t) = at + b'', where ''a'' and ''b'' are computed by the synchronization algorithm.
+
+One could extend the interface for other timestamp transforms, for instance to have a transform where the formula would change over the course of the trace.
+
+== Todo ==
+
+Here's a list of features not yet implemented that would enhance trace synchronization and event matching:
+
+* Ability to select a synchronization algorithm
+* Implement a better way to select the reference trace instead of arbitrarily taking the first in alphabetical order (for instance, the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet))
+* Ability to join traces from the same host so that even if one of the traces is not synchronized with the reference trace, it will take the same timestamp transform as the one on the same machine.
+* Instead of having the timestamp transforms per trace, have the timestamp transform as part of an experiment context, so that the trace's specific analysis, like the state system, are in the original trace, but are transformed only when needed for an experiment analysis.
+* Add more views to display the synchronization information (only textual statistics are available for now)
+
+= Analysis Framework =
+
+Analysis modules are useful to tell the user exactly what can be done with a trace. The analysis framework provides an easy way to access and execute the modules and open the various outputs available.
+
+Analyses can have parameters they can use in their code. They also have outputs registered to them to display the results from their execution.
+
+== Creating a new module ==
+
+All analysis modules must implement the '''IAnalysisModule''' interface from the o.e.l.tmf.core project. An abstract class, '''TmfAbstractAnalysisModule''', provides a good base implementation. It is strongly suggested to use it as a superclass of any new analysis.
+
+=== Example ===
+
+This example shows how to add a simple analysis module for an LTTng kernel trace with two parameters.
+
+<pre>
+public class MyLttngKernelAnalysis extends TmfAbstractAnalysisModule {
+
+ public static final String PARAM1 = "myparam";
+ public static final String PARAM2 = "myotherparam";
+
+ @Override
+ public boolean canExecute(ITmfTrace trace) {
+ /* This just makes sure the trace is an Lttng kernel trace, though
+ usually that should have been done by specifying the trace type
+ this analysis module applies to */
+ if (!LttngKernelTrace.class.isAssignableFrom(trace.getClass())) {
+ return false;
+ }
+
+ /* Does the trace contain the appropriate events? */
+ String[] events = { "sched_switch", "sched_wakeup" };
+ return ((LttngKernelTrace) trace).hasAllEvents(events);
+ }
+
+ @Override
+ protected void canceling() {
+ /* The job I am running in is being cancelled, let's clean up */
+ }
+
+ @Override
+ protected boolean executeAnalysis(final IProgressMonitor monitor) {
+ /*
+ * I am running in an Eclipse job, and I already know I can execute
+ * on a given trace.
+ *
+ * In the end, I will return true if I was successfully completed or
+ * false if I was either interrupted or something wrong occurred.
+ */
+ Object param1 = getParameter(PARAM1);
+ int param2 = (Integer) getParameter(PARAM2);
+ }
+
+ @Override
+ public Object getParameter(String name) {
+ Object value = super.getParameter(name);
+ /* Make sure the value of param2 is of the right type. For sake of
+ simplicity, the full parameter format validation is not presented
+ here */
+ if ((value != null) && name.equals(PARAM2) && (value instanceof String)) {
+ return Integer.parseInt((String) value);
+ }
+ return value;
+ }
+
+}
+</pre>
+
+=== Available base analysis classes and interfaces ===
+
+The following are available as base classes for analysis modules. They also extend the abstract '''TmfAbstractAnalysisModule'''
+
+* '''TmfStateSystemAnalysisModule''': A base analysis module that builds one state system. A module extending this class only needs to provide a state provider and the type of state system backend to use. All state systems should now use this base class as it also contains all the methods to actually create the state sytem with a given backend.
+
+The following interfaces can optionally be implemented by analysis modules if they use their functionalities. For instance, some utility views, like the State System Explorer, may have access to the module's data through these interfaces.
+
+* '''ITmfAnalysisModuleWithStateSystems''': Modules implementing this have one or more state systems included in them. For example, a module may "hide" 2 state system modules for its internal workings. By implementing this interface, it tells that it has state systems and can return them if required.
+
+=== How it works ===
+
+Analyses are managed through the '''TmfAnalysisManager'''. The analysis manager is a singleton in the application and keeps track of all available analysis modules, with the help of '''IAnalysisModuleHelper'''. It can be queried to get the available analysis modules, either all of them or only those for a given tracetype. The helpers contain the non-trace specific information on an analysis module: its id, its name, the tracetypes it applies to, etc.
+
+When a trace is opened, the helpers for the applicable analysis create new instances of the analysis modules. The analysis are then kept in a field of the trace and can be executed automatically or on demand.
+
+The analysis is executed by calling the '''IAnalysisModule#schedule()''' method. This method makes sure the analysis is executed only once and, if it is already running, it won't start again. The analysis itself is run inside an Eclipse job that can be cancelled by the user or the application. The developer must consider the progress monitor that comes as a parameter of the '''executeAnalysis()''' method, to handle the proper cancellation of the processing. The '''IAnalysisModule#waitForCompletion()''' method will block the calling thread until the analysis is completed. The method will return whether the analysis was successfully completed or if it was cancelled.
+
+A running analysis can be cancelled by calling the '''IAnalysisModule#cancel()''' method. This will set the analysis as done, so it cannot start again unless it is explicitly reset. This is done by calling the protected method '''resetAnalysis'''.
+
+== Telling TMF about the analysis module ==
+
+Now that the analysis module class exists, it is time to hook it to the rest of TMF so that it appears under the traces in the project explorer. The way to do so is to add an extension of type ''org.eclipse.linuxtools.tmf.core.analysis'' to a plugin, either through the ''Extensions'' tab of the Plug-in Manifest Editor or by editing directly the plugin.xml file.
+
+The following code shows what the resulting plugin.xml file should look like.
+
+<pre>
+<extension
+ point="org.eclipse.linuxtools.tmf.core.analysis">
+ <module
+ id="my.lttng.kernel.analysis.id"
+ name="My LTTng Kernel Analysis"
+ analysis_module="my.plugin.package.MyLttngKernelAnalysis"
+ automatic="true">
+ <parameter
+ name="myparam">
+ </parameter>
+ <parameter
+ default_value="3"
+ name="myotherparam">
+ <tracetype
+ class="org.eclipse.linuxtools.lttng2.kernel.core.trace.LttngKernelTrace">
+ </tracetype>
+ </module>
+</extension>
+</pre>
+
+This defines an analysis module where the ''analysis_module'' attribute corresponds to the module class and must implement IAnalysisModule. This module has 2 parameters: ''myparam'' and ''myotherparam'' which has default value of 3. The ''tracetype'' element tells which tracetypes this analysis applies to. There can be many tracetypes. Also, the ''automatic'' attribute of the module indicates whether this analysis should be run when the trace is opened, or wait for the user's explicit request.
+
+Note that with these extension points, it is possible to use the same module class for more than one analysis (with different ids and names). That is a desirable behavior. For instance, a third party plugin may add a new tracetype different from the one the module is meant for, but on which the analysis can run. Also, different analyses could provide different results with the same module class but with different default values of parameters.
+
+== Attaching outputs and views to the analysis module ==
+
+Analyses will typically produce outputs the user can examine. Outputs can be a text dump, a .dot file, an XML file, a view, etc. All output types must implement the '''IAnalysisOutput''' interface.
+
+An output can be registered to an analysis module at any moment by calling the '''IAnalysisModule#registerOutput()''' method. Analyses themselves may know what outputs are available and may register them in the analysis constructor or after analysis completion.
+
+The various concrete output types are:
+
+* '''TmfAnalysisViewOutput''': It takes a view ID as parameter and, when selected, opens the view.
+
+=== Using the extension point to add outputs ===
+
+Analysis outputs can also be hooked to an analysis using the same extension point ''org.eclipse.linuxtools.tmf.core.analysis'' in the plugin.xml file. Outputs can be matched either to a specific analysis identified by an ID, or to all analysis modules extending or implementing a given class or interface.
+
+The following code shows how to add a view output to the analysis defined above directly in the plugin.xml file. This extension does not have to be in the same plugin as the extension defining the analysis. Typically, an analysis module can be defined in a core plugin, along with some outputs that do not require UI elements. Other outputs, like views, who need UI elements, will be defined in a ui plugin.
+
+<pre>
+<extension
+ point="org.eclipse.linuxtools.tmf.core.analysis">
+ <output
+ class="org.eclipse.linuxtools.tmf.ui.analysis.TmfAnalysisViewOutput"
+ id="my.plugin.package.ui.views.myView">
+ <analysisId
+ id="my.lttng.kernel.analysis.id">
+ </analysisId>
+ </output>
+ <output
+ class="org.eclipse.linuxtools.tmf.ui.analysis.TmfAnalysisViewOutput"
+ id="my.plugin.package.ui.views.myMoreGenericView">
+ <analysisModuleClass
+ class="my.plugin.package.core.MyAnalysisModuleClass">
+ </analysisModuleClass>
+ </output>
+</extension>
+</pre>
+
+== Providing help for the module ==
+
+For now, the only way to provide a meaningful help message to the user is by overriding the '''IAnalysisModule#getHelpText()''' method and return a string that will be displayed in a message box.
+
+What still needs to be implemented is for a way to add a full user/developer documentation with mediawiki text file for each module and automatically add it to Eclipse Help. Clicking on the Help menu item of an analysis module would open the corresponding page in the help.
+
+== Using analysis parameter providers ==
+
+An analysis may have parameters that can be used during its execution. Default values can be set when describing the analysis module in the plugin.xml file, or they can use the '''IAnalysisParameterProvider''' interface to provide values for parameters. '''TmfAbstractAnalysisParamProvider''' provides an abstract implementation of this interface, that automatically notifies the module of a parameter change.
+
+=== Example parameter provider ===
+
+The following example shows how to have a parameter provider listen to a selection in the LTTng kernel Control Flow view and send the thread id to the analysis.
+
+<pre>
+public class MyLttngKernelParameterProvider extends TmfAbstractAnalysisParamProvider {
+
+ private ControlFlowEntry fCurrentEntry = null;
+
+ private static final String NAME = "My Lttng kernel parameter provider"; //$NON-NLS-1$
+
+ private ISelectionListener selListener = new ISelectionListener() {
+ @Override
+ public void selectionChanged(IWorkbenchPart part, ISelection selection) {
+ if (selection instanceof IStructuredSelection) {
+ Object element = ((IStructuredSelection) selection).getFirstElement();
+ if (element instanceof ControlFlowEntry) {
+ ControlFlowEntry entry = (ControlFlowEntry) element;
+ setCurrentThreadEntry(entry);
+ }
+ }
+ }
+ };
+
+ /*
+ * Constructor
+ */
+ public CriticalPathParameterProvider() {
+ super();
+ registerListener();
+ }
+
+ @Override
+ public String getName() {
+ return NAME;
+ }
+
+ @Override
+ public Object getParameter(String name) {
+ if (fCurrentEntry == null) {
+ return null;
+ }
+ if (name.equals(MyLttngKernelAnalysis.PARAM1)) {
+ return fCurrentEntry.getThreadId()
+ }
+ return null;
+ }
+
+ @Override
+ public boolean appliesToTrace(ITmfTrace trace) {
+ return (trace instanceof LttngKernelTrace);
+ }
+
+ private void setCurrentThreadEntry(ControlFlowEntry entry) {
+ if (!entry.equals(fCurrentEntry)) {
+ fCurrentEntry = entry;
+ this.notifyParameterChanged(MyLttngKernelAnalysis.PARAM1);
+ }
+ }
+
+ private void registerListener() {
+ final IWorkbench wb = PlatformUI.getWorkbench();
+
+ final IWorkbenchPage activePage = wb.getActiveWorkbenchWindow().getActivePage();
+
+ /* Add the listener to the control flow view */
+ view = activePage.findView(ControlFlowView.ID);
+ if (view != null) {
+ view.getSite().getWorkbenchWindow().getSelectionService().addPostSelectionListener(selListener);
+ view.getSite().getWorkbenchWindow().getPartService().addPartListener(partListener);
+ }
+ }
+
+}
+</pre>
+
+=== Register the parameter provider to the analysis ===
+
+To have the parameter provider class register to analysis modules, it must first register through the analysis manager. It can be done in a plugin's activator as follows:
+
+<pre>
+@Override
+public void start(BundleContext context) throws Exception {
+ /* ... */
+ TmfAnalysisManager.registerParameterProvider("my.lttng.kernel.analysis.id", MyLttngKernelParameterProvider.class)
+}
+</pre>
+
+where '''MyLttngKernelParameterProvider''' will be registered to analysis ''"my.lttng.kernel.analysis.id"''. When the analysis module is created, the new module will register automatically to the singleton parameter provider instance. Only one module is registered to a parameter provider at a given time, the one corresponding to the currently selected trace.
+
+== Providing requirements to analyses ==
+
+=== 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).
+
+=== 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()'''.
+
+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.
+
+<pre>
+@Override
+public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
+ Set<TmfAnalysisRequirement> requirements = new HashSet<>();
+
+ /* Create requirements of type 'event' and 'domain' */
+ TmfAnalysisRequirement eventRequirement = new TmfAnalysisRequirement("event");
+ TmfAnalysisRequirement domainRequirement = new TmfAnalysisRequirement("domain");
+
+ /* Add the values */
+ domainRequirement.addValue("kernel", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
+ eventRequirement.addValue("sched_switch", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
+ eventRequirement.addValue("sched_wakeup", TmfAnalysisRequirement.ValuePriorityLevel.OPTIONAL);
+
+ /* An information about the events */
+ eventRequirement.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);
+
+ return requirements;
+}
+</pre>
+
+
+== TODO ==
+
+Here's a list of features not yet implemented that would improve the analysis module user experience:
+
+* Implement help using the Eclipse Help facility (without forgetting an eventual command line request)
+* The abstract class '''TmfAbstractAnalysisModule''' executes an analysis as a job, but nothing compels a developer to do so for an analysis implementing the '''IAnalysisModule''' interface. We should force the execution of the analysis as a job, either from the trace itself or using the TmfAnalysisManager or by some other mean.
+* Views and outputs are often registered by the analysis themselves (forcing them often to be in the .ui packages because of the views), because there is no other easy way to do so. We should extend the analysis extension point so that .ui plugins or other third-party plugins can add outputs to a given analysis that resides in the core.
+* Improve the user experience with the analysis:
+** Allow the user to select which analyses should be available, per trace or per project.
+** Allow the user to view all available analyses even though he has no imported traces.
+** Allow the user to generate traces for a given analysis, or generate a template to generate the trace that can be sent as parameter to the tracer.
+** Give the user a visual status of the analysis: not executed, in progress, completed, error.
+** Give a small screenshot of the output as icon for it.
+** Allow to specify parameter values from the GUI.
+* Add the possibility for an analysis requirement to be composed of another requirement.
+* Generate a trace session from analysis requirements.
+
+
+= Performance Tests =
+
+Performance testing allows to calculate some metrics (CPU time, Memory Usage, etc) that some part of the code takes during its execution. These metrics can then be used as is for information on the system's execution, or they can be compared either with other execution scenarios, or previous runs of the same scenario, for instance, after some optimization has been done on the code.
+
+For automatic performance metric computation, we use the ''org.eclipse.test.performance'' plugin, provided by the Eclipse Test Feature.
+
+== Add performance tests ==
+
+=== Where ===
+
+Performance tests are unit tests and they are added to the corresponding unit tests plugin. To separate performance tests from unit tests, a separate source folder, typically named ''perf'', is added to the plug-in.
+
+Tests are to be added to a package under the ''perf'' directory, the package name would typically match the name of the package it is testing. For each package, a class named '''AllPerfTests''' would list all the performance tests classes inside this package. And like for unit tests, a class named '''AllPerfTests''' for the plug-in would list all the packages' '''AllPerfTests''' classes.
+
+When adding performance tests for the first time in a plug-in, the plug-in's '''AllPerfTests''' class should be added to the global list of performance tests, found in package ''org.eclipse.linuxtools.lttng.alltests'', in class '''RunAllPerfTests'''. This will ensure that performance tests for the plug-in are run along with the other performance tests
+
+=== How ===
+
+TMF is using the org.eclipse.test.performance framework for performance tests. Using this, performance metrics are automatically taken and, if many runs of the tests are run, average and standard deviation are automatically computed. Results can optionally be stored to a database for later use.
+
+Here is an example of how to use the test framework in a performance test:
+
+<pre>
+public class AnalysisBenchmark {
+
+ private static final String TEST_ID = "org.eclipse.linuxtools#LTTng kernel analysis";
+ private static final CtfTmfTestTrace testTrace = CtfTmfTestTrace.TRACE2;
+ private static final int LOOP_COUNT = 10;
+
+ /**
+ * Performance test
+ */
+ @Test
+ public void testTrace() {
+ assumeTrue(testTrace.exists());
+
+ /** Create a new performance meter for this scenario */
+ Performance perf = Performance.getDefault();
+ PerformanceMeter pm = perf.createPerformanceMeter(TEST_ID);
+
+ /** Optionally, tag this test for summary or global summary on a given dimension */
+ perf.tagAsSummary(pm, "LTTng Kernel Analysis", Dimension.CPU_TIME);
+ perf.tagAsGlobalSummary(pm, "LTTng Kernel Analysis", Dimension.CPU_TIME);
+
+ /** The test will be run LOOP_COUNT times */
+ for (int i = 0; i < LOOP_COUNT; i++) {
+
+ /** Start each run of the test with new objects to avoid different code paths */
+ try (IAnalysisModule module = new LttngKernelAnalysisModule();
+ LttngKernelTrace trace = new LttngKernelTrace()) {
+ module.setId("test");
+ trace.initTrace(null, testTrace.getPath(), CtfTmfEvent.class);
+ module.setTrace(trace);
+
+ /** The analysis execution is being tested, so performance metrics
+ * are taken before and after the execution */
+ pm.start();
+ TmfTestHelper.executeAnalysis(module);
+ pm.stop();
+
+ /*
+ * Delete the supplementary files, so next iteration rebuilds
+ * the state system.
+ */
+ File suppDir = new File(TmfTraceManager.getSupplementaryFileDir(trace));
+ for (File file : suppDir.listFiles()) {
+ file.delete();
+ }
+
+ } catch (TmfAnalysisException | TmfTraceException e) {
+ fail(e.getMessage());
+ }
+ }
+
+ /** Once the test has been run many times, committing the results will
+ * calculate average, standard deviation, and, if configured, save the
+ * data to a database */
+ pm.commit();
+ }
+}
+
+</pre>
+
+For more information, see [http://wiki.eclipse.org/Performance/Automated_Tests The Eclipse Performance Test How-to]
+
+Some rules to help write performance tests are explained in section [[#ABC of performance testing | ABC of performance testing]].
+
+=== Run a performance test ===
+
+Performance tests are unit tests, so, just like unit tests, they can be run by right-clicking on a performance test class and selecting ''Run As'' -> ''Junit Plug-in Test''.
+
+By default, if no database has been configured, results will be displayed in the Console at the end of the test.
+
+Here is the sample output from the test described in the previous section. It shows all the metrics that have been calculated during the test.
+
+<pre>
+Scenario 'org.eclipse.linuxtools#LTTng kernel analysis' (average over 10 samples):
+ System Time: 3.04s (95% in [2.77s, 3.3s]) Measurable effect: 464ms (1.3 SDs) (required sample size for an effect of 5% of mean: 94)
+ Used Java Heap: -1.43M (95% in [-33.67M, 30.81M]) Measurable effect: 57.01M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6401)
+ Working Set: 14.43M (95% in [-966.01K, 29.81M]) Measurable effect: 27.19M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6400)
+ Elapsed Process: 3.04s (95% in [2.77s, 3.3s]) Measurable effect: 464ms (1.3 SDs) (required sample size for an effect of 5% of mean: 94)
+ Kernel time: 621ms (95% in [586ms, 655ms]) Measurable effect: 60ms (1.3 SDs) (required sample size for an effect of 5% of mean: 39)
+ CPU Time: 6.06s (95% in [5.02s, 7.09s]) Measurable effect: 1.83s (1.3 SDs) (required sample size for an effect of 5% of mean: 365)
+ Hard Page Faults: 0 (95% in [0, 0]) Measurable effect: 0 (1.3 SDs) (required sample size for an effect of 5% of stdev: 6400)
+ Soft Page Faults: 9.27K (95% in [3.28K, 15.27K]) Measurable effect: 10.6K (1.3 SDs) (required sample size for an effect of 5% of mean: 5224)
+ Text Size: 0 (95% in [0, 0])
+ Data Size: 0 (95% in [0, 0])
+ Library Size: 32.5M (95% in [-12.69M, 77.69M]) Measurable effect: 79.91M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6401)
+</pre>
+
+Results from performance tests can be saved automatically to a derby database. Derby can be run either in embedded mode, locally on a machine, or on a server. More information on setting up derby for performance tests can be found here: [http://wiki.eclipse.org/Performance/Automated_Tests The Eclipse Performance Test How-to]. The following documentation will show how to configure an Eclipse run configuration to store results on a derby database located on a server.
+
+Note that to store results in a derby database, the ''org.apache.derby'' plug-in must be available within your Eclipse. Since it is an optional dependency, it is not included in the target definition. It can be installed via the '''Orbit''' repository, in ''Help'' -> ''Install new software...''. If the '''Orbit''' repository is not listed, click on the latest one from [http://download.eclipse.org/tools/orbit/downloads/] and copy the link under ''Orbit Build Repository''.
+
+To store the data to a database, it needs to be configured in the run configuration. In ''Run'' -> ''Run configurations..'', under ''Junit Plug-in Test'', find the run configuration that corresponds to the test you wish to run, or create one if it is not present yet.
+
+In the ''Arguments'' tab, in the box under ''VM Arguments'', add on separate lines the following information
+
+<pre>
+-Declipse.perf.dbloc=//javaderby.dorsal.polymtl.ca
+-Declipse.perf.config=build=mybuild;host=myhost;config=linux;jvm=1.7
+</pre>
+
+The ''eclipse.perf.dbloc'' parameter is the url (or filename) of the derby database. The database is by default named ''perfDB'', with username and password ''guest''/''guest''. If the database does not exist, it will be created, initialized and populated.
+
+The ''eclipse.perf.config'' parameter identifies a '''variation''': It typically identifies the build on which is it run (commitId and/or build date, etc), the machine (host) on which it is run, the configuration of the system (for example Linux or Windows), the jvm etc. That parameter is a list of ';' separated key-value pairs. To be backward-compatible with the Eclipse Performance Tests Framework, the 4 keys mentioned above are mandatory, but any key-value pairs can be used.
+
+== ABC of performance testing ==
+
+Here follow some rules to help design good and meaningful performance tests.
+
+=== Determine what to test ===
+
+For tests to be significant, it is important to choose what exactly is to be tested and make sure it is reproducible every run. To limit the amount of noise caused by the TMF framework, the performance test code should be tweaked so that only the method under test is run. For instance, a trace should not be "opened" (by calling the ''traceOpened()'' method) to test an analysis, since the ''traceOpened'' method will also trigger the indexing and the execution of all applicable automatic analysis.
+
+For each code path to test, multiple scenarios can be defined. For instance, an analysis could be run on different traces, with different sizes. The results will show how the system scales and/or varies depending on the objects it is executed on.
+
+The number of '''samples''' used to compute the results is also important. The code to test will typically be inside a '''for''' loop that runs exactly the same code each time for a given number of times. All objects used for the test must start in the same state at each iteration of the loop. For instance, any trace used during an execution should be disposed of at the end of the loop, and any supplementary file that may have been generated in the run should be deleted.
+
+Before submitting a performance test to the code review, you should run it a few times (with results in the Console) and see if the standard deviation is not too large and if the results are reproducible.
+
+=== Metrics descriptions and considerations ===
+
+CPU time: CPU time represent the total time spent on CPU by the current process, for the time of the test execution. It is the sum of the time spent by all threads. On one hand, it is more significant than the elapsed time, since it should be the same no matter how many CPU cores the computer has. But since it calculates the time of every thread, one has to make sure that only threads related to what is being tested are executed during that time, or else the results will include the times of those other threads. For an application like TMF, it is hard to control all the threads, and empirically, it is found to vary a lot more than the system time from one run to the other.
+
+System time (Elapsed time): The time between the start and the end of the execution. It will vary depending on the parallelisation of the threads and the load of the machine.
+
+Kernel time: Time spent in kernel mode
+
+Used Java Heap: It is the difference between the memory used at the beginning of the execution and at the end. This metric may be useful to calculate the overall size occupied by the data generated by the test run, by forcing a garbage collection before taking the metrics at the beginning and at the end of the execution. But it will not show the memory used throughout the execution. There can be a large standard deviation. The reason for this is that when benchmarking methods that trigger tasks in different threads, like signals and/or analysis, these other threads might be in various states at each run of the test, which will impact the memory usage calculated. When using this metric, either make sure the method to test does not trigger external threads or make sure you wait for them to finish.
+
+= Network Tracing =
+
+== Adding a protocol ==
+
+Supporting a new network protocol in TMF is straightforward. Minimal effort is required to support new protocols. In this tutorial, the UDP protocol will be added to the list of supported protocols.
+
+=== Architecture ===
+
+All the TMF pcap-related code is divided in three projects (not considering the tests plugins):
+* '''org.eclipse.linuxtools.pcap.core''', which contains the parser that will read pcap files and constructs the different packets from a ByteBuffer. It also contains means to build packet streams, which are conversation (list of packets) between two endpoints. To add a protocol, almost all of the work will be in that project.
+* '''org.eclipse.linuxtools.tmf.pcap.core''', which contains TMF-specific concepts and act as a wrapper between TMF and the pcap parsing library. It only depends on org.eclipse.linuxtools.tmf.core and org.eclipse.pcap.core. To add a protocol, one file must be edited in this project.
+* '''org.eclipse.linuxtools.tmf.pcap.ui''', which contains all TMF pcap UI-specific concepts, such as the views and perspectives. No work is needed in that project.
+
+=== UDP Packet Structure ===
+
+The UDP is a transport-layer protocol that does not guarantee message delivery nor in-order message reception. A UDP packet (datagram) has the following [http://en.wikipedia.org/wiki/User_Datagram_Protocol#Packet_structure structure]:
+
+{| class="wikitable" style="margin: 0 auto; text-align: center;"
+|-
+! style="border-bottom:none; border-right:none;"| ''Offsets''
+! style="border-left:none;"| Octet
+! colspan="8" | 0
+! colspan="8" | 1
+! colspan="8" | 2
+! colspan="8" | 3
+|-
+! style="border-top: none" | Octet
+! <tt>Bit</tt>!!<tt> 0</tt>!!<tt> 1</tt>!!<tt> 2</tt>!!<tt> 3</tt>!!<tt> 4</tt>!!<tt> 5</tt>!!<tt> 6</tt>!!<tt> 7</tt>!!<tt> 8</tt>!!<tt> 9</tt>!!<tt>10</tt>!!<tt>11</tt>!!<tt>12</tt>!!<tt>13</tt>!!<tt>14</tt>!!<tt>15</tt>!!<tt>16</tt>!!<tt>17</tt>!!<tt>18</tt>!!<tt>19</tt>!!<tt>20</tt>!!<tt>21</tt>!!<tt>22</tt>!!<tt>23</tt>!!<tt>24</tt>!!<tt>25</tt>!!<tt>26</tt>!!<tt>27</tt>!!<tt>28</tt>!!<tt>29</tt>!!<tt>30</tt>!!<tt>31</tt>
+|-
+! 0
+!<tt> 0</tt>
+| colspan="16" style="background:#fdd;"| Source port || colspan="16"| Destination port
+|-
+! 4
+!<tt>32</tt>
+| colspan="16"| Length || colspan="16" style="background:#fdd;"| Checksum
+|}
+
+Knowing that, we can define an UDPPacket class that contains those fields.
+
+=== Creating the UDPPacket ===
+
+First, in org.eclipse.linuxtools.pcap.core, create a new package named '''org.eclipse.linuxtools.pcap.core.protocol.name''' with name being the name of the new protocol. In our case name is udp so we create the package '''org.eclipse.linuxtools.pcap.core.protocol.udp'''. All our work is going in this package.
+
+In this package, we create a new class named UDPPacket that extends Packet. All new protocol must define a packet type that extends the abstract class Packet. We also add different fields:
+* ''Packet'' '''fChildPacket''', which is the packet encapsulated by this UDP packet, if it exists. This field will be initialized by findChildPacket().
+* ''ByteBuffer'' '''fPayload''', which is the payload of this packet. Basically, it is the UDP packet without its header.
+* ''int'' '''fSourcePort''', which is an unsigned 16-bits field, that contains the source port of the packet (see packet structure).
+* ''int'' '''fDestinationPort''', which is an unsigned 16-bits field, that contains the destination port of the packet (see packet structure).
+* ''int'' '''fTotalLength''', which is an unsigned 16-bits field, that contains the total length (header + payload) of the packet.
+* ''int'' '''fChecksum''', which is an unsigned 16-bits field, that contains a checksum to verify the integrity of the data.
+* ''UDPEndpoint'' '''fSourceEndpoint''', which contains the source endpoint of the UDPPacket. The UDPEndpoint class will be created later in this tutorial.
+* ''UDPEndpoint'' '''fDestinationEndpoint''', which contains the destination endpoint of the UDPPacket.
+* ''ImmutableMap<String, String>'' '''fFields''', which is a map that contains all the packet fields (see in data structure) which assign a field name with its value. Those values will be displayed on the UI.
+
+We also create the UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) constructor. The parameters are:
+* ''PcapFile'' '''file''', which is the pcap file to which this packet belongs.
+* ''Packet'' '''parent''', which is the packet encasulating this UDPPacket
+* ''ByteBuffer'' '''packet''', which is a ByteBuffer that contains all the data necessary to initialize the fields of this UDPPacket. We will retrieve bytes from it during object construction.
+
+The following class is obtained:
+
+<pre>
+package org.eclipse.linuxtools.pcap.core.protocol.udp;
+
+import java.nio.ByteBuffer;
+import java.util.Map;
+
+import org.eclipse.linuxtools.internal.pcap.core.endpoint.ProtocolEndpoint;
+import org.eclipse.linuxtools.internal.pcap.core.packet.BadPacketException;
+import org.eclipse.linuxtools.internal.pcap.core.packet.Packet;
+
+public class UDPPacket extends Packet {
+
+ private final @Nullable Packet fChildPacket;
+ private final @Nullable ByteBuffer fPayload;
+
+ private final int fSourcePort;
+ private final int fDestinationPort;
+ private final int fTotalLength;
+ private final int fChecksum;
+
+ private @Nullable UDPEndpoint fSourceEndpoint;
+ private @Nullable UDPEndpoint fDestinationEndpoint;
+
+ private @Nullable ImmutableMap<String, String> fFields;
+
+ /**
+ * Constructor of the UDP Packet class.
+ *
+ * @param file
+ * The file that contains this packet.
+ * @param parent
+ * The parent packet of this packet (the encapsulating packet).
+ * @param packet
+ * The entire packet (header and payload).
+ * @throws BadPacketException
+ * Thrown when the packet is erroneous.
+ */
+ public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
+ super(file, parent, Protocol.UDP);
+ // TODO Auto-generated constructor stub
+ }
+
+
+ @Override
+ public Packet getChildPacket() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public ByteBuffer getPayload() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public boolean validate() {
+ // TODO Auto-generated method stub
+ return false;
+ }
+
+ @Override
+ protected Packet findChildPacket() throws BadPacketException {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public ProtocolEndpoint getSourceEndpoint() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public ProtocolEndpoint getDestinationEndpoint() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public Map<String, String> getFields() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public String getLocalSummaryString() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ protected String getSignificationString() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ // TODO Auto-generated method stub
+ return false;
+ }
+
+ @Override
+ public int hashCode() {
+ // TODO Auto-generated method stub
+ return 0;
+ }
+
+}
+</pre>
+
+Now, we implement the constructor. It is done in four steps:
+* We initialize fSourceEndpoint, fDestinationEndpoint and fFields to null, since those are lazy-loaded. This allows faster construction of the packet and thus faster parsing.
+* We initialize fSourcePort, fDestinationPort, fTotalLength, fChecksum using ByteBuffer packet. Thanks to the packet data structure, we can simply retrieve packet.getShort() to get the value. Since there is no unsigned in Java, special care is taken to avoid negative number. We use the utility method ConversionHelper.unsignedShortToInt() to convert it to an integer, and initialize the fields.
+* Now that the header is parsed, we take the rest of the ByteBuffer packet to initialize the payload, if there is one. To do this, we simply generate a new ByteBuffer starting from the current position.
+* We initialize the field fChildPacket using the method findChildPacket()
+
+The following constructor is obtained:
+<pre>
+ public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
+ super(file, parent, Protocol.UDP);
+
+ // The endpoints and fFields are lazy loaded. They are defined in the get*Endpoint()
+ // methods.
+ fSourceEndpoint = null;
+ fDestinationEndpoint = null;
+ fFields = null;
+
+ // Initialize the fields from the ByteBuffer
+ packet.order(ByteOrder.BIG_ENDIAN);
+ packet.position(0);
+
+ fSourcePort = ConversionHelper.unsignedShortToInt(packet.getShort());
+ fDestinationPort = ConversionHelper.unsignedShortToInt(packet.getShort());
+ fTotalLength = ConversionHelper.unsignedShortToInt(packet.getShort());
+ fChecksum = ConversionHelper.unsignedShortToInt(packet.getShort());
+
+ // Initialize the payload
+ if (packet.array().length - packet.position() > 0) {
+ byte[] array = new byte[packet.array().length - packet.position()];
+ packet.get(array);
+
+ ByteBuffer payload = ByteBuffer.wrap(array);
+ payload.order(ByteOrder.BIG_ENDIAN);
+ payload.position(0);
+ fPayload = payload;
+ } else {
+ fPayload = null;
+ }
+
+ // Find child
+ fChildPacket = findChildPacket();
+
+ }
+</pre>
+
+Then, we implement the following methods:
+* ''public Packet'' '''getChildPacket()''': simple getter of fChildPacket
+* ''public ByteBuffer'' '''getPayload()''': simple getter of fPayload
+* ''public boolean'' '''validate()''': method that checks if the packet is valid. In our case, the packet is valid if the retrieved checksum fChecksum and the real checksum (that we can compute using the fields and payload of UDPPacket) are the same.
+* ''protected Packet'' '''findChildPacket()''': method that create a new packet if a encapsulated protocol is found. For instance, based on the fDestinationPort, it could determine what the encapsulated protocol is and creates a new packet object.
+* ''public ProtocolEndpoint'' '''getSourceEndpoint()''': method that initializes and returns the source endpoint.
+* ''public ProtocolEndpoint'' '''getDestinationEndpoint()''': method that initializes and returns the destination endpoint.
+* ''public Map<String, String>'' '''getFields()''': method that initializes and returns the map containing the fields matched to their value.
+* ''public String'' '''getLocalSummaryString()''': method that returns a string summarizing the most important fields of the packet. There is no need to list all the fields, just the most important one. This will be displayed on UI.
+* ''protected String'' '''getSignificationString()''': method that returns a string describing the meaning of the packet. If there is no particular meaning, it is possible to return getLocalSummaryString().
+* public boolean'' '''equals(Object obj)''': Object's equals method.
+* public int'' '''hashCode()''': Object's hashCode method.
+
+We get the following code:
+<pre>
+ @Override
+ public @Nullable Packet getChildPacket() {
+ return fChildPacket;
+ }
+
+ @Override
+ public @Nullable ByteBuffer getPayload() {
+ return fPayload;
+ }
+
+ /**
+ * Getter method that returns the UDP Source Port.
+ *
+ * @return The source Port.
+ */
+ public int getSourcePort() {
+ return fSourcePort;
+ }
+
+ /**
+ * Getter method that returns the UDP Destination Port.
+ *
+ * @return The destination Port.
+ */
+ public int getDestinationPort() {
+ return fDestinationPort;
+ }
+
+ /**
+ * {@inheritDoc}
+ *
+ * See http://www.iana.org/assignments/service-names-port-numbers/service-
+ * names-port-numbers.xhtml or
+ * http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers
+ */
+ @Override
+ protected @Nullable Packet findChildPacket() throws BadPacketException {
+ // When more protocols are implemented, we can simply do a switch on the fDestinationPort field to find the child packet.
+ // For instance, if the destination port is 80, then chances are the HTTP protocol is encapsulated. We can create a new HTTP
+ // packet (after some verification that it is indeed the HTTP protocol).
+ ByteBuffer payload = fPayload;
+ if (payload == null) {
+ return null;
+ }
+
+ return new UnknownPacket(getPcapFile(), this, payload);
+ }
+
+ @Override
+ public boolean validate() {
+ // Not yet implemented. ATM, we consider that all packets are valid.
+ // TODO Implement it. We can compute the real checksum and compare it to fChecksum.
+ return true;
+ }
+
+ @Override
+ public UDPEndpoint getSourceEndpoint() {
+ @Nullable
+ UDPEndpoint endpoint = fSourceEndpoint;
+ if (endpoint == null) {
+ endpoint = new UDPEndpoint(this, true);
+ }
+ fSourceEndpoint = endpoint;
+ return fSourceEndpoint;
+ }
+
+ @Override
+ public UDPEndpoint getDestinationEndpoint() {
+ @Nullable UDPEndpoint endpoint = fDestinationEndpoint;
+ if (endpoint == null) {
+ endpoint = new UDPEndpoint(this, false);
+ }
+ fDestinationEndpoint = endpoint;
+ return fDestinationEndpoint;
+ }
+
+ @Override
+ public Map<String, String> getFields() {
+ ImmutableMap<String, String> map = fFields;
+ if (map == null) {
+ @SuppressWarnings("null")
+ @NonNull ImmutableMap<String, String> newMap = ImmutableMap.<String, String> builder()
+ .put("Source Port", String.valueOf(fSourcePort)) //$NON-NLS-1$
+ .put("Destination Port", String.valueOf(fDestinationPort)) //$NON-NLS-1$
+ .put("Length", String.valueOf(fTotalLength) + " bytes") //$NON-NLS-1$ //$NON-NLS-2$
+ .put("Checksum", String.format("%s%04x", "0x", fChecksum)) //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
+ .build();
+ fFields = newMap;
+ return newMap;
+ }
+ return map;
+ }
+
+ @Override
+ public String getLocalSummaryString() {
+ return "Src Port: " + fSourcePort + ", Dst Port: " + fDestinationPort; //$NON-NLS-1$ //$NON-NLS-2$
+ }
+
+ @Override
+ protected String getSignificationString() {
+ return "Source Port: " + fSourcePort + ", Destination Port: " + fDestinationPort; //$NON-NLS-1$ //$NON-NLS-2$
+ }
+
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ result = prime * result + fChecksum;
+ final Packet child = fChildPacket;
+ if (child != null) {
+ result = prime * result + child.hashCode();
+ } else {
+ result = prime * result;
+ }
+ result = prime * result + fDestinationPort;
+ final ByteBuffer payload = fPayload;
+ if (payload != null) {
+ result = prime * result + payload.hashCode();
+ } else {
+ result = prime * result;
+ }
+ result = prime * result + fSourcePort;
+ result = prime * result + fTotalLength;
+ return result;
+ }
+
+ @Override
+ public boolean equals(@Nullable Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj == null) {
+ return false;
+ }
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ UDPPacket other = (UDPPacket) obj;
+ if (fChecksum != other.fChecksum) {
+ return false;
+ }
+ final Packet child = fChildPacket;
+ if (child != null) {
+ if (!child.equals(other.fChildPacket)) {
+ return false;
+ }
+ } else {
+ if (other.fChildPacket != null) {
+ return false;
+ }
+ }
+ if (fDestinationPort != other.fDestinationPort) {
+ return false;
+ }
+ final ByteBuffer payload = fPayload;
+ if (payload != null) {
+ if (!payload.equals(other.fPayload)) {
+ return false;
+ }
+ } else {
+ if (other.fPayload != null) {
+ return false;
+ }
+ }
+ if (fSourcePort != other.fSourcePort) {
+ return false;
+ }
+ if (fTotalLength != other.fTotalLength) {
+ return false;
+ }
+ return true;
+ }
+</pre>
+
+The UDPPacket class is implemented. We now have the define the UDPEndpoint.
+
+=== Creating the UDPEndpoint ===
+
+For the UDP protocol, an endpoint will be its source or its destination port, depending if it is the source endpoint or destination endpoint. Knowing that, we can create our UDPEndpoint class.
+
+We create in our package a new class named UDPEndpoint that extends ProtocolEndpoint. We also add a field: fPort, which contains the source or destination port. We finally add a constructor public ExampleEndpoint(Packet packet, boolean isSourceEndpoint):
+* ''Packet'' '''packet''': the packet to build the endpoint from.
+* ''boolean'' '''isSourceEndpoint''': whether the endpoint is the source endpoint or destination endpoint.
+
+We obtain the following unimplemented class:
+
+<pre>
+package org.eclipse.linuxtools.pcap.core.protocol.udp;
+
+import org.eclipse.linuxtools.internal.pcap.core.endpoint.ProtocolEndpoint;
+import org.eclipse.linuxtools.internal.pcap.core.packet.Packet;
+
+public class UDPEndpoint extends ProtocolEndpoint {
+
+ private final int fPort;
+
+ public UDPEndpoint(Packet packet, boolean isSourceEndpoint) {
+ super(packet, isSourceEndpoint);
+ // TODO Auto-generated constructor stub
+ }
+
+ @Override
+ public int hashCode() {
+ // TODO Auto-generated method stub
+ return 0;
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ // TODO Auto-generated method stub
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ // TODO Auto-generated method stub
+ return null;
+ }
+
+}
+</pre>
+
+For the constructor, we simply initialize fPort. If isSourceEndpoint is true, then we take packet.getSourcePort(), else we take packet.getDestinationPort().
+
+<pre>
+ /**
+ * Constructor of the {@link UDPEndpoint} class. It takes a packet to get
+ * its endpoint. Since every packet has two endpoints (source and
+ * destination), the isSourceEndpoint parameter is used to specify which
+ * endpoint to take.
+ *
+ * @param packet
+ * The packet that contains the endpoints.
+ * @param isSourceEndpoint
+ * Whether to take the source or the destination endpoint of the
+ * packet.
+ */
+ public UDPEndpoint(UDPPacket packet, boolean isSourceEndpoint) {
+ super(packet, isSourceEndpoint);
+ fPort = isSourceEndpoint ? packet.getSourcePort() : packet.getDestinationPort();
+ }
+</pre>
+
+Then we implement the methods:
+* ''public int'' '''hashCode()''': method that returns an integer based on the fields value. In our case, it will return an integer depending on fPort, and the parent endpoint that we can retrieve with getParentEndpoint().
+* ''public boolean'' '''equals(Object obj)''': method that returns true if two objects are equals. In our case, two UDPEndpoints are equal if they both have the same fPort and have the same parent endpoint that we can retrieve with getParentEndpoint().
+* ''public String'' '''toString()''': method that returns a description of the UDPEndpoint as a string. In our case, it will be a concatenation of the string of the parent endpoint and fPort as a string.
+
+<pre>
+ @Override
+ public int hashCode() {
+ final int prime = 31;
+ int result = 1;
+ ProtocolEndpoint endpoint = getParentEndpoint();
+ if (endpoint == null) {
+ result = 0;
+ } else {
+ result = endpoint.hashCode();
+ }
+ result = prime * result + fPort;
+ return result;
+ }
+
+ @Override
+ public boolean equals(@Nullable Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (!(obj instanceof UDPEndpoint)) {
+ return false;
+ }
+
+ UDPEndpoint other = (UDPEndpoint) obj;
+
+ // Check on layer
+ boolean localEquals = (fPort == other.fPort);
+ if (!localEquals) {
+ return false;
+ }
+
+ // Check above layers.
+ ProtocolEndpoint endpoint = getParentEndpoint();
+ if (endpoint != null) {
+ return endpoint.equals(other.getParentEndpoint());
+ }
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ ProtocolEndpoint endpoint = getParentEndpoint();
+ if (endpoint == null) {
+ @SuppressWarnings("null")
+ @NonNull String ret = String.valueOf(fPort);
+ return ret;
+ }
+ return endpoint.toString() + '/' + fPort;
+ }
+</pre>
+
+=== Registering the UDP protocol ===
+
+The last step is to register the new protocol. There are three places where the protocol has to be registered. First, the parser has to know that a new protocol has been added. This is defined in the enum org.eclipse.linuxtools.pcap.core.protocol.PcapProtocol. Simply add the protocol name here, along with a few arguments:
+* ''String'' '''longname''', which is the long version of name of the protocol. In our case, it is "User Datagram Protocol".
+* ''String'' '''shortName''', which is the shortened name of the protocol. In our case, it is "UDP".
+* ''Layer'' '''layer''', which is the layer to which the protocol belongs in the OSI model. In our case, this is the layer 4.
+* ''boolean'' '''supportsStream''', which defines whether or not the protocol supports packet streams. In our case, this is set to true.
+
+Thus, the following line is added in the PcapProtocol enum:
+<pre>
+ UDP("User Datagram Protocol", "udp", Layer.LAYER_4, true),
+</pre>
+
+Also, TMF has to know about the new protocol. This is defined in org.eclipse.linuxtools.tmf.pcap.core.protocol.TmfPcapProtocol. We simply add it, with a reference to the corresponding protocol in PcapProtocol. Thus, the following line is added in the TmfPcapProtocol enum:
+<pre>
+ UDP(PcapProtocol.UDP),
+</pre>
+
+You will also have to update the ''ProtocolConversion'' class to register the protocol in the switch statements. Thus, for UDP, we add:
+<pre>
+ case UDP:
+ return TmfPcapProtocol.UDP;
+</pre>
+and
+<pre>
+ case UDP:
+ return PcapProtocol.UDP;
+</pre>
+
+Finally, all the protocols that could be the parent of the new protocol (in our case, IPv4 and IPv6) have to be notified of the new protocol. This is done by modifying the findChildPacket() method of the packet class of those protocols. For instance, in IPv4Packet, we add a case in the switch statement of findChildPacket, if the Protocol number matches UDP's protocol number at the network layer:
+<pre>
+ @Override
+ protected @Nullable Packet findChildPacket() throws BadPacketException {
+ ByteBuffer payload = fPayload;
+ if (payload == null) {
+ return null;
+ }
+
+ switch (fIpDatagramProtocol) {
+ case IPProtocolNumberHelper.PROTOCOL_NUMBER_TCP:
+ return new TCPPacket(getPcapFile(), this, payload);
+ case IPProtocolNumberHelper.PROTOCOL_NUMBER_UDP:
+ return new UDPPacket(getPcapFile(), this, payload);
+ default:
+ return new UnknownPacket(getPcapFile(), this, payload);
+ }
+ }
+</pre>
+
+The new protocol has been added. Running TMF should work just fine, and the new protocol is now recognized.
+
+== Adding stream-based views ==
+
+To add a stream-based View, simply monitor the TmfPacketStreamSelectedSignal in your view. It contains the new stream that you can retrieve with signal.getStream(). You must then make an event request to the current trace to get the events, and use the stream to filter the events of interest. Therefore, you must also monitor TmfTraceOpenedSignal, TmfTraceClosedSignal and TmfTraceSelectedSignal. Examples of stream-based views include a view that represents the packets as a sequence diagram, or that shows the TCP connection state based on the packets SYN/ACK/FIN/RST flags. A (very very very early) draft of such a view can be found at https://git.eclipse.org/r/#/c/31054/.
+
+== TODO ==
+
+* Add more protocols. At the moment, only four protocols are supported. The following protocols would need to be implemented: ARP, SLL, WLAN, USB, IPv6, ICMP, ICMPv6, IGMP, IGMPv6, SCTP, DNS, FTP, HTTP, RTP, SIP, SSH and Telnet. Other VoIP protocols would be nice.
+* Add a network graph view. It would be useful to produce graphs that are meaningful to network engineers, and that they could use (for presentation purpose, for instance). We could use the XML-based analysis to do that!
+* Add a Stream Diagram view. This view would represent a stream as a Sequence Diagram. It would be updated when a TmfNewPacketStreamSignal is thrown. It would be easy to see the packet exchange and the time delta between each packet. Also, when a packet is selected in the Stream Diagram, it should be selected in the event table and its content should be shown in the Properties View. See https://git.eclipse.org/r/#/c/31054/ for a draft of such a view.
+* Make adding protocol more "plugin-ish", via extension points for instance. This would make it easier to support new protocols, without modifying the source code.
+* Control dumpcap directly from eclipse, similar to how LTTng is controlled in the Control View.
+* Support pcapng. See: http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html for the file format.
+* Add SWTBOT tests to org.eclipse.linuxtools.tmf.pcap.ui
+* Add a Raw Viewer, similar to Wireshark. We could use the “Show Raw” in the event editor to do that.
+* Externalize strings in org.eclipse.linuxtools.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass Developer Guide
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin>
+<!-- This part should be in a documentation plugin -->
+<!-- Configure the help contribution for this plugin -->
+ <extension point="org.eclipse.help.toc">
+ <toc
+ file="doc/Developer-Guide-toc.xml"
+ primary="true" />
+ </extension>
+</plugin>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2011, Red Hat, Inc.
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <artifactId>org.eclipse.tracecompass.doc</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.eclipse.tracecompass.doc.dev</artifactId>
+ <version>0.1.0-SNAPSHOT</version>
+ <packaging>eclipse-plugin</packaging>
+
+ <name>Trace Compass Developer Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-documentation</id>
+ <phase>generate-sources</phase>
+ <configuration>
+ <echo>Generating TMF Help Files</echo>
+ <target>
+ <property name="compile_classpath" refid="maven.compile.classpath" />
+ <ant target="build" inheritRefs="true" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>clean-documentation</id>
+ <phase>clean</phase>
+ <configuration>
+ <echo>Cleaning up generated TMF Help Files</echo>
+ <target>
+ <ant target="clean" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-launcher</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-nodeps</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
+
+ <groupId>org.eclipse.tracecompass</groupId>
+</project>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
+<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
+<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
+<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
+<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.doc.user" type="4"/> </resources>}"/>
+<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
+<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/>
+<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.doc.user"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.doc.user/build.xml}"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
+<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
+</launchConfiguration>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.eclipse.tracecompass.doc.user</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
+ <triggers>clean,full,incremental,</triggers>
+ <arguments>
+ <dictionary>
+ <key>LaunchConfigHandle</key>
+ <value><project>/.externalToolBuilders/Lttng Help Build.launch</value>
+ </dictionary>
+ <dictionary>
+ <key>incclean</key>
+ <value>true</value>
+ </dictionary>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.ManifestBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.SchemaBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.pde.PluginNature</nature>
+ </natures>
+</projectDescription>
--- /dev/null
+eclipse.preferences.version=1
+encoding/<project>=UTF-8
--- /dev/null
+eclipse.preferences.version=1
+line.separator=\n
--- /dev/null
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-Vendor: %Bundle-Vendor
+Bundle-Version: 0.1.0.qualifier
+Bundle-Localization: plugin
+Bundle-SymbolicName: org.eclipse.tracecompass.doc.user;singleton:=true
+Require-Bundle: org.eclipse.help
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+<title>About</title>
+</head>
+<body lang="EN-US">
+<h2>About This Content</h2>
+
+<p>June 5, 2006</p>
+<h3>License</h3>
+
+<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
+at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+For purposes of the EPL, "Program" will mean the Content.</p>
+
+<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
+being redistributed by another party ("Redistributor") and different terms and conditions may
+apply to your use of any object code in the Content. Check the Redistributor's license that was
+provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
+
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+/* following font face declarations need to be removed for DBCS */
+
+
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
+pre { font-family: Courier, monospace}
+
+/* end font face declarations */
+
+/* following font size declarations should be OK for DBCS */
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
+pre { font-size: 12pt}
+
+/* end font size declarations */
+
+body { background: #FFFFFF}
+h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
+h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
+h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
+h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
+h5 { font size: 13.5pt; }
+p { font-size: 12pt; }
+pre { margin-left: 6; font-size: 9pt }
+
+a:link { color: #006699 }
+a:visited { color: #996699 }
+a:hover { color: #006699 }
+
+ul { margin-top: 0; margin-bottom: 10 }
+li { margin-top: 0; margin-bottom: 0 }
+li p { margin-top: 0; margin-bottom: 0 }
+ol { margin-top: 0; margin-bottom: 10 }
+dl { margin-top: 0; margin-bottom: 10 }
+dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
+dd { margin-top: 0; margin-bottom: 0 }
+strong { font-weight: bold}
+em { font-style: italic}
+var { font-style: italic}
+div.revision { border-left-style: solid; border-left-width: thin;
+ border-left-color: #7B68EE; padding-left:5 }
+th { font-weight: bold }
+.hidden {
+ display: none;
+}
+
+/* Mike Behm's addition to the style sheet */
+.userinput { font-family: monospace; }
+.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
+.notetitle {
+ color: #000000;
+ font-family: helvetica, arial, sans-serif;
+ font-weight: bold;
+ }
+div.linux {display:none;}
+.firsterm {font-style:italic;}
+
+.typewriter {font-family:monospace;}
+.bold {font-weight:600;}
+.linethrough {text-decoration: line-through;}
+.underline {text-decoration: underline;}
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+bin.includes = plugin.xml,\
+ META-INF/,\
+ about.html,\
+ plugin.properties,\
+ book.css,\
+ doc/,\
+ reference/
+jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
+ platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
+src.includes = about.html
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="org.eclipse.tracecompass.doc.user" default="build">
+ <description>
+ Generate Eclipse help content for the Trace Compass user guide
+ </description>
+
+ <!-- Set correct values -->
+ <property name="help.doc.url.base" value="http://wiki.eclipse.org" />
+ <property name="ug.path" value="Linux_Tools_Project/LTTng2/User_Guide" />
+ <property name="ug.title" value="LTTng Plug-in User Guide" />
+
+ <path id="wikitext.tasks.classpath">
+ <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
+ <fileset dir="${osgi.syspath}" erroronmissingdir="false">
+ <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
+ <include name="com.google.guava_*.jar" />
+ </fileset>
+
+ <!-- For Maven builds: use the compile_classpath -->
+ <pathelement path="${compile_classpath}" />
+ </path>
+
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
+ <!-- Different location in more recent versions of Mylyn (Luna ?) -->
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
+
+ <target name="build" description="Generate Eclipse help content for the Trace Compass User Guide">
+ <wikitext-to-eclipse-help markupLanguage="MediaWiki"
+ validate="true"
+ failonvalidationerror="true"
+ overwrite="true"
+ multipleOutputFiles="true"
+ navigationimages="true"
+ title="${ug.title}"
+ formatoutput="true"
+ helpPrefix="doc">
+ <fileset dir="./doc">
+ <include name="User-Guide.mediawiki" />
+ </fileset>
+ <stylesheet url="book.css" />
+ </wikitext-to-eclipse-help>
+ <antcall target="test" />
+ </target>
+
+ <target name="test" description="Verify that all of the HTML files are well-formed XML">
+ <!--
+ Don't bother with DTD validation: we only care if the files are well-formed.
+ We therefore provide an empty DTD
+ -->
+ <xmlvalidate lenient="true">
+ <fileset dir="doc">
+ <include name="**/*.html" />
+ </fileset>
+ <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
+ </xmlvalidate>
+ </target>
+
+
+ <!-- If you need a proxy for the "download" target, set it here -->
+ <!--
+ <setproxy proxyhost="host" proxyport="port"/>
+ -->
+
+ <target name="download" description="Download the current contents of the Trace Compass User Guide from the Eclipse wiki">
+ <mediawiki-to-eclipse-help wikiBaseUrl="${help.doc.url.base}" title="${ug.title}" formatoutput="true" dest="." templateExcludes="*eclipseproject*">
+ <path name="${ug.path}" title="${ug.title}" generateToc="false" />
+ <stylesheet url="book.css" />
+ <pageAppendum>
+= Updating This Document =
+
+This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit
+http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide.
+ </pageAppendum>
+ </mediawiki-to-eclipse-help>
+ </target>
+
+ <target name ="clean" description="Delete all generated files">
+ <delete failonerror="false" includeemptydirs="true">
+ <!-- Files under doc/ (generated locally) -->
+ <fileset dir="doc" includes="**/*.html" />
+ <fileset dir="doc" includes="**/*.xml" />
+
+ <!-- Files downloaded from the Eclipse wiki -->
+ <fileset dir="Linux_Tools_Project" />
+ <fileset file="toc.xml" />
+ </delete>
+ </target>
+
+</project>
--- /dev/null
+*.html
+*.xml
--- /dev/null
+
+= Table of Contents =
+
+__TOC__
+
+= Overview =
+
+LTTng (Linux Trace Toolkit, next generation) is a highly efficient tracing tool for Linux that can be used to track down kernel and application performance issues as well as troubleshoot problems involving multiple concurrent processes and threads. It consists of a set of kernel modules, daemons - to collect the raw tracing data - and a set of tools to control, visualize and analyze the generated data. It also provides support for user space application instrumentation.
+For more information about LTTng, refer to the project [http://lttng.org site]
+
+'''Note''': This User Guide covers the integration of the latest LTTng (up to v2.4) in Eclipse.
+
+== About Tracing ==
+
+Tracing is a troubleshooting technique used to understand the behavior of an instrumented application by collecting information on its execution path. A tracer is the software used for tracing. Tracing can be used to troubleshoot a wide range of bugs that are otherwise extremely challenging. These include, for example, performance problems in complex parallel systems or real-time systems.
+
+Tracing is similar to logging: it consists in recording events that happen in a system at selected execution locations. However, compared to logging, it is generally aimed at developers and it usually records low-level events at a high rate. Tracers can typically generate thousands of events per second. The generated traces can easily contain millions of events and have sizes from many megabytes to tens of gigabytes. Tracers must therefore be optimized to handle a lot of data while having a small impact on the system.
+
+Traces may include events from the operating system kernel (IRQ handler entry/exit, system call entry/exit, scheduling activity, network activity, etc). They can also consists of application events (a.k.a UST - User Space Tracing) or a mix of the two.
+
+For the maximum level of detail, tracing events may be viewed like a log file. However, trace analyzers and viewers are available to derive useful information from the raw data coupled with knowledge of the traced program. These programs must be specially designed to handle quickly the enormous amount of data a trace may contain.
+
+== LTTng integration ==
+
+The LTTng plug-in for Eclipse provides an Eclipse integration for the control of the LTTng tracer as well as fetching and visualization of the traces produced. It also provides the foundation for user-defined analysis tools.
+
+The LTTng Eclipse plug-in provides the following views:
+
+* ''Project'' - an extension to the standard Eclipse Project view tailored for tracing projects
+* ''Control'' - to control the tracer and configure the tracepoints
+* ''Events'' - a versatile view that presents the raw events in tabular format with support for searching, filtering and bookmarking
+* ''Statistics'' - a view that that provides simple statistics on event occurrences by type
+* ''Histogram'' - a view that displays the event density with respect to time in traces
+
+These views can be extended or tailored for specific trace types (e.g. kernel, HW, user app).
+
+At present, the LTTng Eclipse plug-in for Eclipse supports the following kernel-oriented views:
+
+* ''Control Flow'' - to visualize processes state transitions
+* ''Resources'' - to visualize system resources state transitions
+* ''CPU usage'' - to visualize the usage of the processor with respect to the time in traces
+
+It also supports the following User Space traces views:
+
+* ''Memory Usage'' - to visualize the memory usage per thread with respect to time in the traces
+* ''Call Stack'' - to visualize the call stack's evolution over time
+
+Although the control and fetching parts are targeted at the LTTng tracer, the underlying framework can also be used to process any trace that complies with the ''Common Trace Format'' ([http://www.efficios.com/ctf CTF]). CTF specifies a very efficient and compact binary trace format that is meant to be application-, architecture-, and language-agnostic.
+
+== Features ==
+
+The LTTng Eclipse plug-in has a number of features to allow efficient handling of very large traces (and sets of large traces):
+
+* Support for arbitrarily large traces (larger than available memory)
+* Support for correlating multiple time-ordered traces
+* Support for zooming down to the nanosecond on any part of a trace or set of traces
+* Views synchronization of currently selected time or time range, and window time range
+* Efficient searching and filtering of events
+* Support for trace bookmarks
+* Support for importing and exporting trace packages
+
+There is also support for the integration of non-LTTng trace types:
+
+* Built-in CTF parser
+* Dynamic creation of customized parsers (for XML and text traces)
+* Dynamic creation of customized state systems (from XML files)
+* Dynamic creation of customized views (from XML files)
+
+= Installation =
+
+This section describes the installation of the LTTng tracer and the LTTng Eclipse plug-ins as well as their dependencies.
+
+== LTTng Tracer ==
+
+While the Eclipse plug-ins can run on the standard Eclipse platforms (Linux, Mac, Windows), the LTTng tracer and its accompanying tools run on Linux.
+
+The tracer and tools have been available for download in Ubuntu since 12.04. They can easily be installed with the following command:
+
+<pre>
+ > sudo apt-get install lttng-tools
+</pre>
+
+For other distributions, older Ubuntu distributions, or the latest, bleeding edge LTTng tracer, please refer to the [http://lttng.org/download LTTng website] for installation information.
+
+'''Note''': The LTTng tracer (and accompanying tools) is required only if you want to create your own traces (the usual case). If you intend to simply analyze existing traces then it is not necessary to install the tracer.
+
+== LTTng Eclipse Plug-ins ==
+
+The easiest way to install the LTTng plug-ins for Eclipse is through the Software Updates and Add-ons menu. For information on how to use this menu, refer to this [http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site link].
+
+The LTTng plug-ins are structured as a stack of features/plug-ins as following:
+
+* '''CTF''' - A CTF parser that can also be used as a standalone component
+** ''Feature'': org.eclipse.linuxtools.ctf
+** ''Plug-ins'': org.eclipse.linuxtools.ctf.core, org.eclipse.linuxtools.ctf.parser
+
+* '''State System Core''' - State system for TMF
+** ''Plug-ins'': org.eclipse.linuxtools.statesystem.core
+
+* '''TMF''' - ''Tracing and Monitoring Framework'' a framework for generic trace processing
+** ''Feature'': org.eclipse.linuxtools.tmf
+** ''Plug-ins'': org.eclipse.linuxtools.tmf.core, org.eclipse.linuxtools.tmf.ui. org.eclipse.linuxtools.tmf.analysis.xml.core, org.eclipse.linuxtools.tmf.analysis.xml.ui
+
+* '''CTF support for TMF''' - CTF support for the TMF Feature
+** ''Feature'': org.eclipse.linuxtools.tmf.ctf
+** ''Plug-ins'': org.eclipse.linuxtools.tmf.ctf.core
+
+* '''LTTng''' - The wrapper for the LTTng tracer control. Can be used for kernel or application tracing.
+** ''Feature'': org.eclipse.linuxtools.lttng2.control
+** ''Plug-ins'': org.eclipse.linuxtools.lttng2.control.core, org.eclipse.linuxtools.lttng2.control.ui
+
+* '''LTTng Kernel''' - Analysis components specific to Linux kernel traces
+** ''Feature'': org.eclipse.linuxtools.lttng2.kernel
+** ''Plug-ins'': org.eclipse.linuxtools.lttng2.kernel.core, org.eclipse.linuxtools.lttng2.kernel.ui
+
+* '''LTTng UST''' - Analysis components specific to Linux userspace traces
+** ''Feature'': org.eclipse.linuxtools.lttng2.ust
+** ''Plug-ins'': org.eclipse.linuxtools.lttng2.ust.core, org.eclipse.linuxtools.lttng2.ust.ui
+
+== LTTng Eclipse Dependencies ==
+
+The Eclipse LTTng controls the LTTng tracer through an ''ssh'' connection, if the tracer is running locally it can use or bypass the ''ssh'' connection.
+
+Therefore, the target system (where the tracer runs) needs to run an ''ssh'' server as well as ''sftp'' server (for file transfer) to which you have permission to connect.
+
+On the host side (where Eclipse is running), you also need to have Eclipse Remote Services installed to handle the SSH connection and transport. The Remote Services can be installed the standard way (''Help'' > ''Install New Software...'' > ''General Purpose Tools'' > ''Remote Services'').
+
+== Installation Verification ==
+
+If you do not have any, sample LTTng traces can be found here [http://lttng.org/download]. At the bottom of the page there is a link to some sample LTTng 2.0 kernel traces. The trace needs to be uncompressed to be read.
+
+Here are the quick steps to verify that your installation is functional:
+
+* Start Eclipse
+* Open the LTTng perspective
+* Create a Tracing project
+** Right-click in the Project view and select "New Project"
+** Enter the name of your project (e.g. "MyLTTngProject")
+** The project will be created. It will contain 2 empty folders: "Traces" and "Experiments"
+* Open a sample trace
+** Right-click on the newly created project "Traces" folder and select "Open Trace..."
+** Navigate to the sample LTTng trace that you want to visualize and select any file in the trace folder
+** The newly imported trace should appear under the Traces folder
+* Visualize the trace
+** Expand the Traces folder
+** Double-click on the trace
+** The trace should load and the views be populated
+
+If an error message is displayed, you might want to double-check that the trace type is correctly set (right-click on the trace and "Select Trace Type...").
+
+Refer to [[#Tracing Perspective]] for detailed description of the views and their usage.
+
+= LTTng =
+
+== Tracing Perspective ==
+
+The '''Tracing''' perspective is part of the '''Tracing and Monitoring Framework (TMF)''' and groups the following views:
+
+* [[#Project_View | Project View]]
+* [[#Events_Editor | Events Editor]]
+* [[#Histogram_View | Histogram View]]
+* [[#Statistics_View | Statistics View]]
+
+The views are synchronized i.e. selecting an event, a timestamp, a time range, etc will update the other views accordingly.
+
+[[Image:images/TracingPerspective.png]]
+
+The perspective can be opened from the Eclipse Open Perspective dialog ('''Window > Open Perspective... > Other''').
+
+[[Image:images/ShowTracingPerspective.png]]
+
+In addition to these views, the '''Tracing and Monitoring Framework (TMF)''' feature provides a set of generic tracing specific views, such as:
+
+* [[#Colors_View | Colors View]]
+* [[#Filters_View | Filters View]]
+* [[#Time_Chart_View | Time Chart View]]
+* [[#State_System_Explorer_View | State System Explorer View]]
+* [[#Call_Stack_View | Call Stack View]]
+
+The framework also supports user creation of [[#Custom_Parsers | Custom Parsers]].
+
+To open one of the above '''Tracing''' views, use the Eclipse Show View dialog ('''Window > Show View > Other...'''). Then select the relevant view from the '''Tracing''' category.
+
+[[Image:images/ShowTracingViews.png]]
+
+Additionally, the '''LTTng''' feature provides an '''LTTng Tracer Control''' functionality. It comes with a dedicated '''Control View'''.
+
+* [[#LTTng_Tracer_Control | LTTng Tracer Control]]
+
+== Project View ==
+
+The project view is the standard Eclipse Project Explorer. '''Tracing''' projects are well integrated in the Eclipse's Common Navigator Framework. The Project Explorer shows '''Tracing''' project with a small "T" decorator in the upper right of the project folder icon.
+
+=== Creating a Tracing Project ===
+
+A new '''Tracing''' project can be created using the New Tracing Project wizard. To create a new '''Tracing''' select '''File > New > Project...''' from the main menu bar or alternatively form the context-sensitive menu (click with right mouse button in the '''Project Explorer'''.
+
+The first page of project wizard will open.
+
+[[Image:images/NewTracingProjectPage1.png]]
+
+In the list of project categories, expand category '''Tracing''' and select '''Tracing Project''' and the click on '''Next >'''. A second page of the wizard will show. Now enter the a name in the field '''Project Name''', select a location if required and the press on '''Finish'''.
+
+[[Image:images/NewTracingProjectPage2.png]]
+
+A new project will appear in the '''Project Explorer''' view.
+
+[[Image:images/NewProjectExplorer.png]]
+
+Tracing projects have two sub-folders: '''Traces''' which holds the individual traces, and '''Experiments''' which holds sets of traces that we want to correlate.
+
+=== Importing Traces to the Project ===
+
+The '''Traces''' folder holds the set of traces available for a tracing project. It can optionally contain a tree of trace folders to organize traces into sub-folders. The following chapters will explain different ways to import traces to the '''Traces''' folder of a tracing project.
+
+* [[#Opening a Trace | Opening a Trace]]
+* [[#Importing | Importing]]
+* [[#Drag and Drop | Drag and Drop]]
+
+==== Opening a Trace ====
+
+To open a trace, right-click on a target trace folder and select '''Open Trace...'''.
+
+[[Image:images/OpenTraceFile.png]]
+
+A new dialog will show for selecting a trace to open. Select a trace file and then click on '''OK'''. Note that for traces that are directories (such as Common Trace Format (CTF) traces) any file in the trace directory can be selected to open the trace. Now, the trace viewer will attempt to detect the trace types of the selected trace. The auto detection algorithm will validate the trace against all known trace types. If multiple trace types are valid, a trace type is chosen based on a confidence criteria. The validation process and the computation of the confidence level are trace type specific. After successful validation the trace will be linked into the selected target trace folder and then opened with the detected trace type.
+
+Note that a trace type is an extension point of the '''Tracing and Monitoring Framework (TMF)'''. Depending on the which features are loaded, the list of available trace types can vary.
+
+==== Importing ====
+
+To import a set of traces to a trace folder, right-click on the target folder and select '''Import...''' from the context-sensitive menu.
+
+[[Image:images/ProjectImportTraceAction.png]]
+
+At this point, the '''Import Trace Wizard''' will show for selecting traces to import. By default, it shows the correct destination directory where the traces will be imported to. Now, specify the location of the traces in the '''Root directory'''. For that click on the button '''Browse''', browse the media to the location of the traces and click on '''OK'''. Then select the traces to import in the list of files and folders.
+
+Traces can also be imported from an archive file such as a zip or a tar file by selecting the '''Select archive file''' option then by clicking '''Browse'''. Then select the traces to import in the list of files and folders as usual.
+
+Optionally, select the '''Trace Type''' from the drop-down menu. If '''Trace Type''' is set to '''<Automatic Detection>''', the wizard will attempt to detect the trace types of the selected files. The automatic detection algorithm validates a trace against all known trace types. If multiple trace types are valid, a trace type is chosen based on a confidence criteria. The validation process and the computation of the confidence level are trace type specific. Optionally, '''Import unrecognized traces''' can be selected to import trace files that could not be automatically detected by '''<Automatic Detection>'''.
+
+Select or deselect the checkboxes for '''Overwrite existing trace without warning''', '''Create links in workspace''' and '''Preserve folder structure'''. When all options are configured, click on '''Finish'''.
+
+Note that traces of certain types (e.g. LTTng Kernel) are actually a composite of multiple channel traces grouped under a folder. Either the folder or its files can be selected to import the trace.
+
+The option '''Preserve folder structure''' will create, if necessary, the structure of folders relative to (and excluding) the selected '''Root directory''' (or '''Archive file''') into the target trace folder.
+
+[[Image:images/ProjectImportTraceDialog.png]]
+
+If a trace already exists with the same name in the target trace folder, the user can choose to rename the imported trace, overwrite the original trace or skip the trace. When rename is chosen, a number is appended to the trace name, for example smalltrace becomes smalltrace(2).
+
+[[Image:images/ProjectImportTraceDialogRename.png]]
+
+If one selects '''Rename All''', '''Overwrite All''' or '''Skip All''' the choice will be applied for all traces with a name conflict.
+
+Upon successful importing, the traces will be stored in the target trace folder. If a trace type was associated to a trace, then the corresponding icon will be displayed. If no trace type is detected the default editor icon associated with this file type will be displayed. Linked traces will have a little arrow as decorator on the right bottom corner.
+
+Note that trace type is an extension point of the '''Tracing and Monitoring Framework (TMF)'''. Depending on the which features are loaded, the list of trace types can vary.
+
+Alternatively, one can open the '''Import...''' menu from the '''File''' main menu, then select '''Tracing''' > '''Trace Import''' and click on '''Next >'''.
+
+[[Image:images/ProjectImportWizardSelect.png]]
+
+At this point, the '''Import Trace Wizard''' will show. To import traces to the tracing project, follow the instructions that were described above.
+
+==== Drag and Drop ====
+
+Traces can be also be imported to a project by dragging from another tracing project and dropping to the project's target trace folder. The trace will be copied and the trace type will be set.
+
+Any resource can be dragged and dropped from a non-tracing project, and any file or folder can be dragged from an external tool, into a tracing project's trace folder. The resource will be copied or imported as a new trace and it will be attempted to detect the trace types of the imported resource. The automatic detection algorithm validates a trace against all known trace types. If multiple trace types are valid, a trace type is chosen based on a confidence criteria. The validation process and the computation of the confidence level are trace type specific. If no trace type is detected the user needs to set the trace type manually.
+
+To import the trace as a link, use the platform-specific key modifier while dragging the source trace. A link will be created in the target project to the trace's location on the file system.
+
+If a folder containing traces is dropped on a trace folder, the full directory structure will be copied or linked to the target trace folder. The trace type of the contained traces will not be auto-detected.
+
+It is also possible to drop a trace, resource, file or folder into an existing experiment. If the item does not already exist as a trace in the project's trace folder, it will first be copied or imported, then the trace will be added to the experiment.
+
+=== Trace Package Exporting and Importing ===
+
+A trace package is an archive file that contains the trace itself and can also contain its bookmarks and its supplementary files. Including supplementary files in the package can improve performance of opening an imported trace but at the expense of package size.
+
+==== Exporting ====
+
+The '''Export Trace Package Wizard''' allows users to select a trace and export its files and bookmarks to an archive on a media.
+
+The '''Traces''' folder holds the set of traces available for a tracing project. To export traces contained in the '''Traces''' folder, one can open the '''Export...''' menu from the '''File''' main menu. Then select '''Trace Package Export'''
+
+[[Image:images/tracePackageImages/fileExport.png]]
+
+At this point, the '''Trace Package Export''' is opened. The project containing the traces has to be selected first then the traces to be exported.
+
+[[Image:images/tracePackageImages/chooseTrace.png]]
+
+One can also open the wizard and skip the first page by expanding the project, selecting traces or trace folders under the '''Traces''' folder, then right-clicking and selecting the '''Export Trace Package...''' menu item in the context-sensitive menu.
+
+[[Image:images/tracePackageImages/exportSelectedTrace.png]]
+
+Next, the user can choose the content to export and various format options for the resulting file.
+
+[[Image:images/tracePackageImages/exportPackage.png]]
+
+The '''Trace''' item is always selected and represents the files that constitute the trace. The '''Supplementary files''' items represent files that are typically generated when a trace is opened by the viewer. Sharing these files can speed up opening a trace dramatically but also increases the size of the exported archive file. The ''Size'' column can help to decide whether or not to include these files. Lastly, by selecting '''Bookmarks''', the user can export all the bookmarks so that they can be shared along with the trace.
+
+The '''To archive file''' field is used to specify the location where to save the resulting archive.
+
+The '''Options''' section allows the user to choose between a tar archive or a zip archive. Compression can also be toggled on or off.
+
+When Finish button is clicked, the package is generated and saved to the media. The folder structure of the selected traces relative to the '''Traces''' folder is preserved in the trace package.
+
+==== Importing ====
+
+The '''Import Trace Package Wizard''' allows users to select a previously exported trace package from their media and import the content of the package in the workspace.
+
+The '''Traces''' folder holds the set of traces for a tracing project. To import a trace package to the '''Traces''' folder, one can open the '''Import...''' menu from the '''File''' main menu. Then select '''Trace Package Import'''.
+
+[[Image:images/tracePackageImages/fileImport.png]]
+
+One can also open the wizard by expanding the project name, right-clicking on a target folder under the '''Traces''' folder then selecting '''Import Trace Package...''' menu item in the context-sensitive menu.
+
+[[Image:images/tracePackageImages/importTraceFolder.png]]
+
+At this point, the '''Trace Package Import Wizard''' is opened.
+
+[[Image:images/tracePackageImages/importPackage.png]]
+
+The '''From archive file''' field is used to specify the location of the trace package to export. The user can choose the content to import in the tree.
+
+If the wizard was opened using the File menu, the destination project has to be selected in the '''Into project''' field.
+
+When Finish is clicked, the trace is imported in the target folder. The folder structure from the trace package is restored in the target folder.
+
+=== Selecting a Trace Type ===
+
+If no trace type was selected a trace type has to be associated to a trace before it can be opened. To select a trace type select the relevant trace and click the right mouse button. In the context-sensitive menu, select '''Select Trace Type...''' menu item. A sub-menu will show will all available trace type categories. From the relevant category select the required trace type. The examples, below show how to select the '''Common Trace Format''' types '''LTTng Kernel''' and '''Generic CTF trace'''.
+
+[[Image:images/SelectLTTngKernelTraceType.png]]
+
+[[Image:images/SelectGenericCTFTraceType.png]]
+
+After selecting the trace type, the trace icon will be updated with the corresponding trace type icon.
+
+[[Image:images/ExplorerWithAssociatedTraceType.png]]
+
+=== Opening a Trace or Experiment ===
+
+A trace or experiment can be opened by double-clicking the left mouse button on the trace or experiment in the '''Project Explorer''' view. Alternatively, select the trace or experiment in the in the '''Project Explorer''' view and click the right mouse button. Then select '''Open''' menu item of the context-sensitive menu. If there is no trace type set for a file resource then the file will be opened in the default editor associated with this file type.
+
+[[Image:images/OpenTraceAction.png]]
+
+When opening a trace or experiment, all currently opened views which are relevant for the corresponding trace type will be updated.
+
+If a trace resource is a file (and not a directory), then the '''Open With''' menu item is available in the context-sensitive menu and can be used to open the trace source file with any applicable internal or external editor. In that case the trace will not be processed by the tracing application.
+
+=== Creating a Experiment ===
+
+An experiment consists in an arbitrary number of aggregated traces for purpose of correlation. In the degenerate case, an experiment can consist of a single trace. The experiment provides a unified, time-ordered stream of the individual trace events.
+
+To create an experiment, select the folder '''Experiments''' and click the right mouse button. Then select '''New...'''.
+
+[[Image:images/NewExperimentAction.png]]
+
+A new display will open for entering the experiment name. Type the name of the experiment in the text field '''Experiment Name''' and the click on '''OK'''.
+
+[[Image:images/NewExperimentDialog.png]]
+
+=== Selecting Traces for an Experiment ===
+
+After creating an experiment, traces need to be added to the experiment. To select traces for an experiment select the newly create experiment and click the right mouse button. Select '''Select Traces...''' from the context sensitive menu.
+
+[[Image:images/SelectTracesAction.png]]
+
+A new dialog box will open with a list of available traces. The filter text box can be used to quickly find traces. Use buttons '''Select All''' or '''Deselect All''' to select or deselect all traces. Select the traces to add from the list and then click on '''Finish'''.
+
+[[Image:images/SelectTracesDialog.png]]
+
+Now the selected traces will be linked to the experiment and will be shown under the '''Experiments''' folder.
+
+[[Image:images/ExplorerWithExperiment.png]]
+
+Alternatively, traces can be added to an experiment using [[#Drag_and_Drop | Drag and Drop]].
+
+=== Removing Traces from an Experiment ===
+
+To remove one or more traces for an experiment select the trace(s) to remove under the Experiment folder and click the right mouse button. Select '''Remove''' from the context sensitive menu.
+
+[[Image:images/RemoveTracesAction.png]]
+
+After that the selected trace(s) are removed from the experiment. Note that the traces are still in the '''Traces''' folder.
+
+=== Renaming a Trace or Experiment ===
+
+Traces and Experiment can be renamed from the '''Project Explorer''' view. To rename a trace or experiment select the relevant trace and click the right mouse button. Then select '''Rename...''' from the context sensitive menu. The trace or experiment needs to be closed in order to do this operation.
+
+[[Image:images/RenameTraceAction.png]]
+
+A new dialog box will show for entering a new name. Enter a new trace or experiment name respectively in the relevant text field and click on '''OK'''. If the new name already exists the dialog box will show an error and a different name has to be entered.
+
+[[Image:images/RenameTraceDialog.png]]
+
+[[Image:images/RenameExperimentDialog.png]]
+
+After successful renaming the new name will show in the '''Project Explorer'''. In case of a trace all reference links to that trace will be updated too. Note that linked traces only changes the display name, the underlying trace resource will stay the original name.
+
+Note that all supplementary files will be also handled accordingly (see also [[#Deleting Supplementary Files | Deleting Supplementary Files]]).
+
+=== Copying a Trace or Experiment ===
+
+To copy a trace or experiment select the relevant trace or experiment in the '''Project Explorer''' view and click the right mouse button. Then select '''Copy...''' from the context sensitive menu.
+
+[[Image:images/CopyTraceAction.png]]
+
+A new dialog box will show for entering a new name. Enter a new trace or experiment name respectively in the relevant text field and click on '''OK'''. If the new name already exists the dialog box will show an error and a different name has to be entered.
+
+[[Image:images/CopyTraceDialog.png]]
+
+[[Image:images/CopyExperimentDialog.png]]
+
+After successful copy operation the new trace or experiment respectively will show in the '''Project Explorer'''. In case of a linked trace, the copied trace will be a link to the original trace too.
+
+Note that the directory for all supplementary files will be copied, too. (see also [[#Deleting Supplementary Files | Deleting Supplementary Files]]).
+
+=== Deleting a Trace or Experiment ===
+
+To delete a trace or experiment select the relevant trace or experiment in the '''Project Explorer''' view and click the right mouse button. Then select '''Delete...''' from the context sensitive menu. The trace or experiment needs to be closed in order to do this operation.
+
+[[Image:images/DeleteExperimentAction.png]]
+
+A confirmation dialog box will open. To perform the deletion press '''OK''' otherwise select '''Cancel'''.
+
+[[Image:images/DeleteExperimentConfirmationDialog.png]]
+
+After successful operation the selected trace or experiment will be removed from the project. In case of a linked trace only the link will be removed. The actual trace resource remain on the disk.
+
+Note that the directory for all supplementary files will be deleted, too. (see also [[#Deleting Supplementary Files | Deleting Supplementary Files]]).
+
+=== Deleting Supplementary Files ===
+
+Supplementary files are by definition trace specific files that accompany a trace. These file could be temporary files, persistent indexes or any other persistent data files created by the LTTng integration in Eclipse during parsing a trace. For the LTTng 2.0 trace viewer a persistent state history of the Linux Kernel is created and is stored under the name '''stateHistory.ht'''. The statistics for all traces are stored under '''statistics.ht'''. Other state systems may appear in the same folder as more custom views are added.
+
+All supplementary file are hidden from the user and are handled internally by the TMF. However, there is a possibility to delete the supplementary files so that there are recreated when opening a trace.
+
+To delete all supplementary files from one or many traces and experiments, select the relevant traces and experiments in the '''Project Explorer''' view and click the right mouse button. Then select the '''Delete Supplementary Files...''' menu item from the context-sensitive menu.
+
+[[Image:images/DeleteSupplementaryFilesAction.png]]
+
+A new dialog box will open with a list of supplementary files, grouped under the trace or experiment they belong to. Select the file(s) to delete from the list and press '''OK'''. The traces and experiments that need to be closed in order to do this operation will automatically be closed.
+
+[[Image:images/DeleteSupplementaryFilesDialog.png]]
+
+=== Link with Editor ===
+
+The tracing projects support the feature '''Link With Editor''' of the Project Explorer view. With this feature it is now possible to<br/>
+* select a trace element in the Project Explorer view and the corresponding [[#Events Editor | Events Editor]] will get focus if the relevant trace is open.
+* select an [[#Events Editor | Events Editor]] and the corresponding trace element will be highlighted in the Project Explorer view.
+
+To enable or disable this feature toggle the '''Link With Editor''' button of the Project Explorer view as shown below.
+
+[[Image:images/TMF_LinkWithEditor.png]]
+
+== Events Editor ==
+
+The Events editor shows the basic trace data elements (events) in a tabular format. The editors can be dragged in the editor area so that several traces may be shown side by side. These traces are synchronized by timestamp.
+
+[[Image:images/LTTng2EventsEditor.png]]
+
+The header displays the current trace (or experiment) name.
+
+Being part of the '''Tracing and Monitoring''' Framework, the default table displays the following fields:
+
+* '''Timestamp''': the event timestamp
+* '''Source''': the source of the event
+* '''Type''': the event type and localization
+* '''Reference''' the event reference
+* '''Content''': the raw event content
+
+The first row of the table is the header row a.k.a. the Search and Filter row.
+
+The highlighted event is the ''current event'' and is synchronized with the other views. If you select another event, the other views will be updated accordingly. The properties view will display a more detailed view of the selected event.
+
+An event range can be selected by holding the '''Shift''' key while clicking another event or using any of the cursor keys ('''Up'''', '''Down''', '''PageUp''', '''PageDown''', '''Home''', '''End'''). The first and last events in the selection will be used to determine the current selected time range for synchronization with the other views.
+
+[[Image:images/LTTng2EventProperties.png]]
+
+The Events editor can be closed, disposing a trace. When this is done, all the views displaying the information will be updated with the trace data of the next event editor tab. If all the editor tabs are closed, then the views will display their empty states.
+
+=== Searching and Filtering ===
+
+Searching and filtering of events in the table can be performed by entering matching conditions in one or multiple columns in the header row (the first row below the column header).
+
+To toggle between searching and filtering, click on the 'search' ([[Image:images/TmfEventSearch.gif]]) or 'filter' ([[Image:images/TmfEventFilter.gif]]) icon in the header row's left margin, or right-click on the header row and select '''Show Filter Bar''' or '''Show Search Bar''' in the context menu.
+
+To apply a matching condition to a specific column, click on the column's header row cell, type in a [http://download.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html regular expression] and press the '''ENTER''' key. You can also enter a simple text string and it will be automatically be replaced with a 'contains' regular expression.
+
+When matching conditions are applied to two or more columns, all conditions must be met for the event to match (i.e. 'and' behavior).
+
+To clear all matching conditions in the header row, press the '''DEL''' key.
+
+==== Searching ====
+
+When a searching condition is applied to the header row, the table will select the next matching event starting from the top currently displayed event. Wrapping will occur if there is no match until the end of the trace.
+
+All matching events will have a 'search match' icon in their left margin. Non-matching events will be dimmed.
+
+[[Image:images/DefaultTmfEvents-Search.png]]
+
+Pressing the '''ENTER''' key will search and select the next matching event. Pressing the '''SHIFT-ENTER''' key will search and select the previous matching event. Wrapping will occur in both directions.
+
+Press '''ESC''' to cancel an ongoing search.
+
+Press '''DEL''' to clear the header row and reset all events to normal.
+
+==== Filtering ====
+
+When a filtering condition is entered in the head row, the table will clear all events and fill itself with matching events as they are found from the beginning of the trace.
+
+A status row will be displayed before and after the matching events, dynamically showing how many matching events were found and how many events were processed so far. Once the filtering is completed, the status row icon in the left margin will change from a 'stop' to a 'filter' icon.
+
+[[Image:images/DefaultTmfEvents-Filter.png]]
+
+Press '''ESC''' to stop an ongoing filtering. In this case the status row icon will remain as a 'stop' icon to indicate that not all events were processed.
+
+Press '''DEL''' or right-click on the table and select '''Clear Filters''' from the context menu to clear the header row and remove the filtering. All trace events will be now shown in the table. Note that the currently selected event will remain selected even after the filter is removed.
+
+You can also search on the subset of filtered events by toggling the header row to the Search Bar while a filter is applied. Searching and filtering conditions are independent of each other.
+
+==== Bookmarking ====
+
+Any event of interest can be tagged with a bookmark.
+
+To add a bookmark, double-click the left margin next to an event, or right-click the margin and select '''Add bookmark...'''. Alternatively use the '''Edit''' > '''Add bookmark...''' menu. Edit the bookmark description as desired and press '''OK'''.
+
+The bookmark will be displayed in the left margin, and hovering the mouse over the bookmark icon will display the description in a tooltip.
+
+The bookmark will be added to the '''Bookmarks''' view. In this view the bookmark description can be edited, and the bookmark can be deleted. Double-clicking the bookmark or selecting '''Go to''' from its context menu will open the trace or experiment and go directly to the event that was bookmarked.
+
+To remove a bookmark, double-click its icon, select '''Remove Bookmark''' from the left margin context menu, or select '''Delete''' from the Bookmarks view.
+
+[[Image:images/Bookmarks.png]]
+
+=== Event Source Lookup ===
+
+For CTF traces using specification v1.8.2 or above, information can optionally be embedded in the trace to indicate the source of a trace event. This is accessed through the event context menu by right-clicking on an event in the table.
+
+==== Source Code ====
+
+If a source file is available in the trace for the selected event, the item '''Open Source Code''' is shown in the context menu. Selecting this menu item will attempt to find the source file in all opened projects in the workspace. If multiple candidates exist, a selection dialog will be shown to the user. The selected source file will be opened, at the correct line, in its default language editor. If no candidate is found, an error dialog is shown displaying the source code information.
+
+==== EMF Model ====
+
+If an EMF model URI is available in the trace for the selected event, the item '''Open Model Element''' is shown in the context menu. Selecting this menu item will attempt to open the model file in the project specified in the URI. The model file will be opened in its default model editor. If the model file is not found, an error dialog is shown displaying the URI information.
+
+=== Exporting To Text ===
+It is possible to export the content of the trace to a text file based on the columns displayed in the events table. If a filter (see '''[[#Filtering| Filtering]]''') was defined prior exporting only events that match the filter will be exported to the file. To export the trace to text, press the right mouse button on the events table. A context-sensitive menu will show. Select the '''Export To Text...''' menu option. A file locater dialog will open. Fill in the file name and location and then press on '''OK'''. A window with a progress bar will open till the export is finished.
+
+''Note'': The columns in the text file are separated by tabs.
+
+=== Collapsing of Repetitive Events ===
+The implementation for collapsing of repetitive events is trace type specific and is only available for certain trace types. For example, a trace type could allow collapsing of consecutive events that have the same event content but not the same timestamp. If a trace type supports this feature then it is possible to select the '''Collapse Events''' menu item after pressing the right mouse button in the table.
+
+When the collapsing of events is executing, the table will clear all events and fill itself with all relevant events. If the collapse condition is met, the first column of the table will show the number of times this event was repeated consecutively.
+
+[[Image:images/TablePreCollapse.png]]
+
+A status row will be displayed before and after the events, dynamically showing how many non-collapsed events were found and how many events were processed so far. Once the collapsing is completed, the status row icon in the left margin will change from a 'stop' to a 'filter' icon.
+
+[[Image:images/TablePostCollapse.png]]
+
+To clear collapsing, press the right mouse button in the table and select menu item '''Clear Filters''' in the context sensitive menu. ''Note'' that collapsing is also removed when another filter is applied to the table.
+
+== Histogram View ==
+
+The Histogram View displays the trace events distribution with respect to time. When streaming a trace, this view is dynamically updated as the events are received.
+
+[[Image:images/HistogramView.png]]
+
+The '''Hide Lost Events''' toggle button [[Image:images/hide_lost_events.gif]] in the local toolbar allows to hide the bars of lost events. When the button is selected it can be toggled again to show the lost events.
+
+The '''Activate Trace Coloring''' toggle button [[Image:images/show_hist_traces.gif]] in the local toolbar allows to use separate colors for each trace of an experiment. Note that this feature is not available if your experiment contains more than twenty two traces. When activated, a legend is displayed at the bottom on the histogram view.
+
+On the top left, there are three text controls:
+
+* '''Selection Start''': Displays the start time of the current selection
+* '''Selection End''': Displays the end time of the current selection
+* '''Window Span''': Displays the current zoom window size in seconds
+
+The controls can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly. To modify both selection times simultaneously, press the link icon [[Image:images/link.gif]] which disables the '''Selection End''' control input.
+
+The large (full) histogram, at the bottom, shows the event distribution over the whole trace or set of traces. It also has a smaller semi-transparent orange window, with a cross-hair, that shows the current zoom window.
+
+The smaller (zoom) histogram, on top right, corresponds to the current zoom window, a sub-range of the event set.
+
+The x-axis of each histogram corresponds to the event timestamps. The start time and end time of the histogram range is displayed. The y-axis shows the maximum number of events in the corresponding histogram bars.
+
+The vertical blue line(s) show the current selection time (or range). If applicable, the region in the selection range will be shaded.
+
+The mouse can be used to control the histogram:
+
+* '''Left-click''': Set a selection time
+* '''Left-drag''': Set a selection range
+* '''Shift-left-click or drag''': Extend or shrink the selection range
+
+* '''Middle-click or Ctrl-left-click''': Center the zoom window on mouse (full histogram only)
+* '''Middle-drag or Ctrl-left-drag''': Move the zoom window
+
+* '''Right-drag''': Set the zoom window
+* '''Shift-right-click or drag''': Extend or shrink the zoom window (full histogram only)
+
+* '''Mouse wheel up''': Zoom in
+* '''Mouse wheel down''': Zoom out
+
+Hovering the mouse over an histogram bar pops up an information window that displays the start/end time of the corresponding bar, as well as the number of events (and lost events) it represents. If the mouse is over the selection range, the selection span in seconds is displayed.
+
+In each histogram, the following keys are handled:
+
+* '''Left Arrow''': Moves the current event to the previous non-empty bar
+* '''Right Arrow''': Moves the current event to the next non-empty bar
+* '''Home''': Sets the current time to the first non-empty bar
+* '''End''': Sets the current time to the last non-empty histogram bar
+* '''Plus (+)''': Zoom in
+* '''Minus (-)''': Zoom out
+
+== Statistics View ==
+
+The Statistics View displays the various event counters that are collected when analyzing a trace. The data is organized per trace. After opening a trace, the element '''Statistics''' is added under the '''Tmf Statistics Analysis''' tree element in the Project Explorer. To open the view, double-click the '''Statistics''' tree element. Alternatively, select '''Statistics''' under '''Tracing''' within the '''Show View''' window ('''Window''' -> '''Show View''' -> '''Other...'''). This view shows 3 columns: ''Level'' ''Events total'' and ''Events in selected time range''. After parsing a trace the view will display the number of events per event type in the second column and in the third, the currently selected time range's event type distribution is shown. The cells where the number of events are printed also contain a colored bar with a number that indicates the percentage of the event count in relation to the total number of events. The statistics is collected for the whole trace. This view is part of the '''Tracing and Monitoring Framework (TMF)''' and is generic. It will work for any trace type extensions. For the LTTng 2.0 integration the Statistics view will display statistics as shown below.:
+
+[[Image:images/LTTng2StatisticsView.png]]
+
+By default, the statistics use a state system, therefore will load very quickly once the state system is written to the disk as a supplementary file.
+
+== Colors View ==
+
+[[Image:images/ColorsView.png]]
+
+The Colors view allows the user to define a prioritized list of color settings.
+
+A color setting associates a foreground and background color (used in any events table), and a tick color (used in the Time Chart view), with an event filter.
+
+In an events table, any event row that matches the event filter of a color setting will be displayed with the specified foreground and background colors. If the event matches multiple filters, the color setting with the highest priority will be used.
+
+The same principle applies to the event tick colors in the Time Chart view. If a tick represents many events, the tick color of the highest priority matching event will be used.
+
+Color settings can be inserted, deleted, reordered, imported and exported using the buttons in the Colors view toolbar. Changes to the color settings are applied immediately, and are persisted to disk.
+
+== Filters View ==
+
+[[Image:images/FiltersView.png]]
+
+The Filters view allows the user to define preset filters that can be applied to any events table.
+
+The filters can be more complex than what can be achieved with the filter header row in the events table. The filter is defined in a tree node structure, where the node types can be any of '''EVENTTYPE''', '''AND''', '''OR''', '''CONTAINS''', '''EQUALS''', '''MATCHES''' or '''COMPARE'''. Some nodes types have restrictions on their possible children in the tree.
+
+The '''EVENTTYPE''' node filters against the event type of the trace as defined in a plug-in extension or in a custom parsers. When used, any child node will have its field combo box restricted to the possible fields of that event type.
+
+The '''AND''' node applies the logical ''and'' condition on all of its children. All children conditions must be true for the filter to match. A ''not'' operator can be applied to invert the condition.
+
+The '''OR''' node applies the logical ''or'' condition on all of its children. At least one children condition must be true for the filter to match. A ''not'' operator can be applied to invert the condition.
+
+The '''CONTAINS''' node matches when the specified event ''field'' value contains the specified ''value'' string. A ''not'' operator can be applied to invert the condition. The condition can be case sensitive or insensitive.
+
+The '''EQUALS''' node matches when the specified event ''field'' value equals exactly the specified ''value'' string. A ''not'' operator can be applied to invert the condition. The condition can be case sensitive or insensitive.
+
+The '''MATCHES''' node matches when the specified event ''field'' value matches against the specified ''regular expression''. A ''not'' operator can be applied to invert the condition.
+
+The '''COMPARE''' node matches when the specified event ''field'' value compared with the specified ''value'' gives the specified ''result''. The result can be set to ''smaller than'', ''equal'' or ''greater than''. The type of comparison can be numerical, alphanumerical or based on time stamp. A ''not'' operator can be applied to invert the condition.
+
+Filters can be added, deleted, imported and exported using the buttons in the Filters view toolbar. The nodes in the view can be Cut (Ctrl-X), Copied (Ctrl-C) and Pasted (Ctrl-V) by using the buttons in the toolbar or by using the key bindings. This makes it easier to quickly build new filters from existing ones. Changes to the preset filters are only applied and persisted to disk when the '''save filters''' button is pressed.
+
+To apply a saved preset filter in an events table, right-click on the table and select '''Apply preset filter...''' > ''filter name''.
+
+== Time Chart View ==
+
+[[Image:images/TimeChartView.png]]
+
+The Time Chart view allows the user to visualize every open trace in a common time chart. Each trace is display in its own row and ticks are display for every punctual event. As the user zooms using the mouse wheel or by right-clicking and dragging in the time scale, more detailed event data is computed from the traces.
+
+Time synchronization is enabled between the time chart view and other trace viewers such as the events table.
+
+Color settings defined in the Colors view can be used to change the tick color of events displayed in the Time Chart view.
+
+When a search is applied in the events table, the ticks corresponding to matching events in the Time Chart view are decorated with a marker below the tick.
+
+When a bookmark is applied in the events table, the ticks corresponding to the bookmarked event in the Time Chart view is decorated with a bookmark above the tick.
+
+When a filter is applied in the events table, the non-matching ticks are removed from the Time Chart view.
+
+The Time Chart only supports traces that are opened in an editor. The use of an editor is specified in the plug-in extension for that trace type, or is enabled by default for custom traces.
+
+== State System Explorer View ==
+
+The State System Explorer view allows the user to inspect the state interval values of every attribute of a state system at a particular time.
+
+The view shows a tree of currently selected traces and their registered state system IDs. For each state system the tree structure of attributes is displayed. The attribute name, quark, value, start and end time, and full attribute path are shown for each attribute.
+
+To modify the time of attributes shown in the view, select a different current time in other views that support time synchronization (e.g. event table, histogram view). When a time range is selected, this view uses the begin time.
+
+== Custom Parsers ==
+
+Custom parser wizards allow the user to define their own parsers for text or XML traces. The user defines how the input should be parsed into internal trace events and identifies the event fields that should be created and displayed. Traces created using a custom parser can be correlated with other built-in traces or traces added by plug-in extension.
+
+=== Creating a custom text parser ===
+
+The '''New Custom Text Parser''' wizard can be used to create a custom parser for text logs. It can be launched several ways:
+
+* Select '''File''' > '''New''' > '''Other...''' > '''Tracing''' > '''Custom Text Parser'''
+* Open the '''[[#Managing custom parsers|Manage Custom Parsers]]''' dialog, select the '''Text''' radio button and click the '''New...''' button
+
+[[Image:images/CustomTextParserInput.png]]
+
+Fill out the first wizard page with the following information:
+
+* '''Category:''' Enter a category name for the trace type.
+* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser.
+* '''Time Stamp format:''' Enter the date and time pattern that will be used to output the Time Stamp.<br>
+Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
+
+Click the '''Add next line''', '''Add child line''' or '''Remove line''' buttons to create a new line of input or delete it. For each line of input, enter the following information:
+
+* '''Regular expression:''' Enter a regular expression that should match the input line in the log, using capturing groups to extract the data.<br>
+Note: information about date and time patterns can be found here: [http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html]
+
+* '''Cardinality:''' Enter the minimum and maximum number of lines matching this line's regular expression that must be found in the log. At least the minimum number of lines must be found before the parser will consider the next line. Child lines will always be considered first.
+
+<u>Important note:</u> The custom parsers identify a log entry when the first line's regular expression matches (Root Line n). Each subsequent text line in the log is attempted to be matched against the regular expression of the parser's input lines in the order that they are defined (Line n.*). Only the first matching input line will be used to process the captured data to be stored in the log entry. When a text line matches a Root Line's regular expression, a new log entry is started.
+
+Click the '''Add group''' or '''Remove group''' buttons to define the data extracted from the capturing groups in the line's regular expression. For each group, enter the following information:
+
+* '''Name combo:''' Select a name for the extracted data:
+** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Message''': Select this option to identify the main log entry's message. This is usually a group which could have text of greater length.
+** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box.
+
+* '''Action combo:''' Select the action to be performed on the extracted data:
+** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this group.
+** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this group.
+** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this group, using a | separator between matches.
+
+The '''Preview input''' text box can be used to enter any log data that will be processed against the defined custom parser. When the wizard is invoked from a selected log file resource, this input will be automatically filled with the file contents.
+
+The '''Preview:''' text field of each capturing group and of the Time Stamp will be filled from the parsed data of the first matching log entry.
+
+In the '''Preview input''' text box, the matching entries are highlighted with different colors:
+
+* <code><span style="background:#FFFF00"> Yellow </span></code> : indicates uncaptured text in a matching line.
+* <code><span style="background:#00FF00"> Green </span></code> : indicates a captured group in the matching line's regular expression for which a custom parser group is defined. This data will be stored by the custom parser.
+* <code><span style="background:#FF00FF"> Magenta</span></code> : indicates a captured group in the matching line's regular expression for which there is no custom parser group defined. This data will be lost.
+* <code> White </code> : indicates a non-matching line.
+
+The first line of a matching entry is highlighted with darker colors.
+
+By default only the first matching entry will be highlighted. To highlight all matching entries in the preview input data, click the '''Highlight All''' button. This might take a few seconds to process, depending on the input size.
+
+Click the '''Next >''' button to go to the second page of the wizard.
+
+[[Image:images/CustomTextParserOutput.png]]
+
+On this page, the list of default and custom data is shown, along with a preview of the custom parser log table output.
+
+The custom data output can be modified by the following options:
+
+* '''Visibility:''' Select or unselect the checkbox to display the custom data or hide it.
+
+* '''Column order:''' Click '''Move before''' or '''Move after''' to change the display order of custom data.
+
+The table at the bottom of the page shows a preview of the custom parser log table output according to the selected options, using the matching entries of the previous page's '''Preview input''' log data.
+
+Click the '''Finish''' button to close the wizard and save the custom parser.
+
+=== Creating a custom XML parser ===
+
+The '''New Custom XML Parser''' wizard can be used to create a custom parser for XML logs. It can be launched several ways:
+
+* Select '''File''' > '''New''' > '''Other...''' > '''Tracing''' > '''Custom XML Parser'''
+* Open the '''[[#Managing custom parsers|Manage Custom Parsers]]''' dialog, select the '''XML''' radio button and click the '''New...''' button
+
+[[Image:images/CustomXMLParserInput.png]]
+
+Fill out the first wizard page with the following information:
+
+* '''Category:''' Enter a category name for the trace type.
+* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser.
+* '''Time Stamp format:''' Enter the date and time pattern that will be used to output the Time Stamp.<br>
+
+Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
+
+Click the '''Add document element''' button to create a new document element and enter a name for the root-level document element of the XML file.
+
+Click the '''Add child''' button to create a new element of input to the document element or any other element. For each element, enter the following information:
+
+* '''Element name:''' Enter a name for the element that must match an element of the XML file.
+* '''Log entry:''' Select this checkbox to identify an element which represents a log entry. Each element with this name in the XML file will be parsed to a new log entry. At least one log entry element must be identified in the XML document. Log entry elements cannot be nested.
+* '''Name combo:''' Select a name for the extracted data:
+** '''Ignore''': Select this option to ignore the extracted element's data at this level. It is still possible to extract data from this element's child elements.
+** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Message''': Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
+** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box. It does not have to match the element name.
+* '''Action combo:''' Select the action to be performed on the extracted data:
+** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this element.
+** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this element.
+** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this element, using a | separator between matches.
+
+Note: An element's extracted data 'value' is a parsed string representation of all its attributes, children elements and their own values. To extract more specific information from an element, ignore its data value and extract the data from one or many of its attributes and children elements.
+
+Click the '''Add attribute''' button to create a new attribute input from the document element or any other element. For each attribute, enter the following information:
+
+* '''Attribute name:''' Enter a name for the attribute that must match an attribute of this element in the XML file.
+* '''Name combo:''' Select a name for the extracted data:
+** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Message''': Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
+** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box. It does not have to match the element name.
+* '''Action combo:''' Select the action to be performed on the extracted data:
+** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this element.
+** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this element.
+** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this element, using a | separator between matches.
+
+Note: A log entry can inherited input data from its parent elements if the data is extracted at a higher level.
+
+Click the '''Feeling lucky''' button to automatically and recursively create child elements and attributes for the current element, according to the XML element data found in the '''Preview input''' text box, if any.
+
+Click the '''Remove element''' or '''Remove attribute''' buttons to remove the extraction of this input data. Take note that all children elements and attributes are also removed.
+
+The '''Preview input''' text box can be used to enter any XML log data that will be processed against the defined custom parser. When the wizard is invoked from a selected log file resource, this input will be automatically filled with the file contents.
+
+The '''Preview:''' text field of each capturing element and attribute and of the Time Stamp will be filled from the parsed data of the first matching log entry. Also, when creating a new child element or attribute, its element or attribute name will be suggested if possible from the preview input data.
+
+Click the '''Next >''' button to go to the second page of the wizard.
+
+[[Image:images/CustomXMLParserOutput.png]]
+
+On this page, the list of default and custom data is shown, along with a preview of the custom parser log table output.
+
+The custom data output can be modified by the following options:
+
+* '''Visibility:''' Select or unselect the checkbox to display the custom data or hide it.
+* '''Column order:''' Click '''Move before''' or '''Move before''' to change the display order of custom data.
+
+The table at the bottom of the page shows a preview of the custom parser log table output according to the selected options, using the matching entries of the previous page's '''Preview input''' log data.
+
+Click the '''Finish''' button to close the wizard and save the custom parser.
+
+=== Managing custom parsers ===
+
+The '''Manage Custom Parsers''' dialog is used to manage the list of custom parsers used by the tool. To open the dialog:
+
+* Open the '''Project Explorer''' view.
+* Select '''Manage Custom Parsers...''' from the '''Traces''' folder context menu, or from a trace's '''Select Trace Type...''' context sub-menu.
+
+[[Image:images/ManageCustomParsers.png]]
+
+The ordered list of currently defined custom parsers for the selected type is displayed on the left side of the dialog.
+
+To change the type of custom parser to manage, select the '''Text''' or '''XML''' radio button.
+
+The following actions can be performed from this dialog:
+
+* New...
+
+Click the '''New...''' button to launch the '''New Custom Parser''' wizard.
+
+* Edit...
+
+Select a custom parser from the list and click the '''Edit...''' button to launch the '''Edit Custom Parser''' wizard.
+
+* Delete
+
+Select a custom parser from the list and click the '''Delete''' button to remove the custom parser.
+
+* Import...
+
+Click the '''Import...''' button and select a file from the opened file dialog to import all its custom parsers. If any parser conflicts with an existing built-in or custom trace type, the user will be prompted to skip or rename the imported parser.
+
+* Export...
+
+Select a custom parser from the list, click the '''Export...''' button and enter or select a file in the opened file dialog to export the custom parser. Note that if an existing file containing custom parsers is selected, the custom parser will be appended to the file.
+
+=== Opening a trace using a custom parser ===
+
+Once a custom parser has been created, any [[#Importing Traces to the Project|imported trace]] file can be opened and parsed using it.
+
+To do so:
+
+* Select a trace in the '''Project Explorer''' view
+* Right-click the trace and select '''Select Trace Type...''' > ''category name'' > ''parser name''
+* Double-click the trace or right-click it and select '''Open'''
+
+The trace will be opened in an editor showing the events table, and an entry will be added for it in the Time Chart view.
+
+= LTTng Tracer Control =
+
+The LTTng Tracer Control in Eclipse for the LTTng Tracer toolchain version v2.0 (or later) is done using SSH and requires an SSH server to be running on the remote host. For the SSH connection the SSH implementation of Remote Services is used. The functions to control the LTTng tracer (e.g. start and stop), either locally or remotely, are available from a dedicated Control View.
+
+In the following sections the LTTng 2.0 tracer control integration in Eclipse is described. Please refer to the LTTng 2.0 tracer control command line manual for more details and descriptions about all commands and their command line parameters [[#References | References]].
+
+== Control View ==
+To open the Control View, select '''Window->Show View->Other...->LTTng->Control View''.
+
+[[Image:images/LTTngControlView.png]]
+
+=== Creating a New Connection to a Remote Host ===
+
+To connect to a remote host, select the '''New Connection''' button in the Control View.
+
+[[Image:images/LTTngControlViewConnect.png]]
+
+A new dialog is opened for selecting a remote connection. You can also edit or define a remote connection from here.
+
+[[Image:images/LTTng2NewConnection.png]]
+
+To define a new remote host using the default SSH service, select '''Buit-in SSH''' and then select '''Create...'''. This will start the standard '''New Connection''' wizard provided by the Remote Services plugin. Similar, to edit the definition of a remote connection, select '''Edit...''' and use the '''Edit Connection''' wizard provided by the SSH service. In case you have installed an additional adapter for the Remote Services, you can choose to define a remote connection based on this adapter.
+
+[[Image:images/LTTng2NewRemoteConnection.png]]
+
+To use an existing connection definition, select the relevant entry in the tree and then select '''Ok'''.
+
+[[Image:images/LTTng2SelectConnection.png]]
+
+A new display will show for providing the user name and password. This display only opens if no password had been saved before. Enter user name and password in the '''Password Required''' dialog box and select '''Ok'''.
+
+[[Image:images/LTTng2EnterPassword.png]]
+
+After pressing '''Ok''' the SSH connection will be established and after successful login the Control View implementation retrieves the LTTng Tracer Control information. This information will be displayed in the Control View in form of a tree structure.
+
+[[Image:images/LTTng2ControlViewFilled.png]]
+
+The top level tree node is the representation of the remote connection (host). The connection name of the connection will be displayed. Depending on the connection state different icons are displayed. If the node is '''CONNECTED''' the icon is shown [[Image:images/Target_connected.gif]], otherwise (states '''CONNECTING''', '''DISCONNNECTING''' or '''DISCONNECTED''' the icon is [[Image:images/Target_disconnected.gif]].
+
+Under the host level two folder groups are located. The first one is the '''Provider''' group. The second one is the '''Sessions''' group.
+
+Under the '''Provider''' group all trace providers are displayed. Trace providers are '''Kernel''' and any user space application that supports UST tracing. Under each provider a corresponding list of events are displayed.
+
+Under the '''Sessions''' group all current sessions will be shown. The level under the sessions show the configured domains. Currently the LTTng 2.0 Tracer Toolchan supports domain '''Kernel''' and '''UST global'''. Under each domain the configured channels will be displayed. The last level is under the channels where the configured events are displayed.
+
+Each session can be '''ACTIVE''' or '''INACTIVE'''. Active means that tracing has been started, inactive means that the tracing has been stopped. Depending on the state of a session a different icon is displayed. The icon for an active session is [[Image:images/Session_active.gif]]. The icon for an inactive session is [[Image:images/Session_inactive.gif]].
+
+Each channel can be '''ENABLED''' or '''DISABLED'''. An enabled channel means that all configured events of that channel will be traced and a disabled channel won't trace any of its configured events. Different icons are displayed depending on the state of the channel. The icon for an enabled channel is [[Image:images/Channel.gif]] and the icon for a disabled channel is [[Image:images/Channel_disabled.gif]].
+
+Events within a channel can be in state '''ENABLED''' or '''DISABLED'''. Enabled events are stored in the trace when passed during program execution. Disabled events on the other hand won't be traced. Depending on the state of the event the icons for the event is different. An enabled event has the icon [[Image:images/Event_enabled.gif]] and a disabled event the icon [[Image:images/Event_disabled.gif]].
+
+=== Disconnecting from a Remote Host ===
+
+To disconnect from a remote host, select the host in the Control View and press the '''Disconnect''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Disconnect''' button.
+
+[[Image:images/LTTng2ControlViewDisconnect.png]]
+
+=== Connecting to a Remote Host ===
+
+To connect to a remote host, select the host in the Control View and press the '''Connect''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Connect''' button. This will start the connection process as discribed in [[#Creating a New Connection to a Remote Host | Creating a New Connection to a Remote Host]].
+
+[[Image:images/LTTng2ControlViewConnect.png]]
+
+=== Deleting to a Remote Host Connection ===
+
+To delete a remote host connection, select the host in the Control View and press the '''Delete''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Delete''' button. For that command to be active the connection state has to be '''DISCONNECTED''' and the trace has to be closed.
+
+[[Image:images/LTTng2ControlViewDelete.png]]
+
+=== Creating a Tracing Session ===
+To create a tracing session, select the tree node '''Sessions''' and press the right mouse button. Then select the '''Create Session...''' button of the context-sensitive menu.
+
+[[Image:images/LTTng2CreateSessionAction.png]]
+
+A dialog box will open for entering information about the session to be created.
+
+[[Image:images/LTTng2CreateSessionDialog.png]]
+
+Fill in the '''Session Name''' and optionally the '''Session Path''' and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
+
+=== Creating a Tracing Session With Advanced Options ===
+LTTng Tools version v2.1.0 introduces the possibility to configure the trace output location at session creation time. The trace can be stored in the (tracer) local file system or can be transferred over the network.
+
+To create a tracing session and configure the trace output, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]]. A dialog box will open for entering information about the session to be created.
+
+[[Image:images/LTTng2CreateSessionDialog_Advanced.png]]
+
+The button '''Advanced >>>''' will only show if the remote host has LTTng Tools v2.1.0 installed. To configure the trace output select the '''Advanced >>>''' button. The Dialog box will be shown new fields to configure the trace output location.
+
+[[Image:images/LTTng2CreateSessionDialog_TracePath.png]]
+
+By default, the button '''Use same protocol and address for data and control''' is selected which allows to configure the same '''Protocol''' and '''Address''' for both data URL and control URL.
+
+If button '''Use same protocol and address for data and control''' is selected the '''Protocol''' can be '''net''' for the default network protocol which is TCP (IPv4), '''net6''' for the default network protocol which is TCP (IPv6) and '''file''' for the local file system. For '''net''' and '''net6''' the port can be configured. Enter a value in '''Port''' for data and control URL or keep them empty for the default port to be used. Using '''file''' as protocol no port can be configured and the text fields are disabled.
+
+If button '''Use same protocol and address for data and control''' is not selected the '''Protocol''' can be '''net''' for the default network protocol which is TCP (IPv4), '''net6''' for the default network protocol which is TCP (IPv6), '''tcp''' for the network protocol TCP (IPv4) and '''tcp6''' for the network protocol TCP (IPv6). Note that for '''net''' and '''net6''' always the default port is used and hence the port text fields are disabled. To configure non-default ports use '''tcp''' or '''tcp6'''.
+
+The text field '''Trace Path''' allows for specifying the path relative to the location defined by the '''relayd''' or relative to the location specified by the '''Address''' when using protocol '''file'''. For more information about the '''relayd''' see '''LTTng relayd User Manual''' in chapter [[#References | References]].
+
+To create a session with advanced options, fill in the relevant parameters and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
+
+=== Creating a Snapshot Tracing Session ===
+LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After starting tracing the trace events are not stored on disk or over the network. They are only transfered to disk or over the network when the user records a snapshot. To create such a snapshot session, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]].
+
+[[Image:images/LTTng2CreateSessionDialog_Snapshot.png]]
+
+Fill in all necessary information, select the radio button for '''Snapshot Mode''' and press '''Ok'''. By default, the location for the snapshot output will be on the host where the host is located.
+
+Refer to chapter [[#Recording a Snapshot | Recording a Snapshot]] for how to create a snapshot.
+
+=== Creating a Live Tracing Session ====
+LTTng Tools version v2.4.0 introduces the possibility to create live tracing sessions. The live mode allows you to stream the trace and view it while it's being recorded. To create such a live session, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]].
+
+[[Image:images/LTTng2CreateSessionDialog_Live.png]]
+
+In the advanced options, it is possible to set the '''Live Delay'''. The '''Live Delay''' is the delay in micro seconds before the data is flushed and streamed.
+
+[[Image:images/LTTng2CreateSessionDialog_Live_Advanced.png]]
+
+Fill in all necessary information, select the radio button for '''Live Mode''' and press '''Ok'''.
+
+=== Enabling Channels - General ===
+
+Enabling channels can be done using a session tree node when the domain hasn't be created in the session or, alternatively on a domain tree node of a session in case the domain is already available.
+
+=== Enabling Channels On Session Level ===
+
+To enable a channel, select the tree node of the relevant session and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
+
+[[Image:images/LTTng2CreateChannelAction.png]]
+
+A dialog box will open for entering information about the channel to be created.
+
+[[Image:images/LTTng2CreateChannelDialog.png]]
+
+By default the domain '''Kernel''' is selected. To create a UST channel, select '''UST''' under the domain section. The label <Default> in any text box indicates that the default value of the tracer will be configured. To initialize the dialog box press button '''Default'''.
+
+If required update the following channel information and then press '''Ok'''.
+
+* '''Channel Name''': The name of the channel.
+* '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
+* '''Number of Sub Buffers''': The number of sub-buffers of the channel.
+* '''Switch Timer Interval''': The switch timer interval.
+* '''Read Timer Interval''': The read timer interval.
+* '''Discard Mode''': '''Overwrite''' events in buffer or '''Discard''' new events when buffer is full.
+
+Upon successful operation, the requested domain will be created under the session tree node as well as the requested channel will be added under the domain. The channel will be '''ENABLED'''.
+
+=== Configuring Trace File Rotation ===
+
+Since LTTng Tools v2.2.0 it is possible to set the maximum size of trace files and the maximum number of them. These options are located in the same dialog box that is used for enabling channels.
+
+[[Image:images/LTTng2CreateChannelDialogFileRotation.png]]
+
+* '''Maximum size of trace files''': The maximum size of trace files
+* '''Maximum number of trace files''': The maximum number of trace files
+
+=== Configuring per UID and per PID Buffers (UST only) ===
+
+Since LTTng Tools v2.2.0 it is possible to configure the type of buffers for '''UST''' application. It is now possible to choose between per '''UID''' buffers (per user ID) and per '''PID''' buffers (per process ID) using the dialog box for enabling channels.
+
+[[Image:images/LTTng2CreateChannelDialogPerUIDBuffers.png]]
+
+* '''Per PID buffers''': To activate the per PID buffers option for UST channels
+* '''Per UID buffers''': To activate the per UID buffers option for UST channels
+
+If no buffer type is selected then the default value of the tracer will be configured.
+
+Note that '''Global shared buffers''' is only for kernel channel and is pre-selected when '''Kernel''' is selected in the dalog box.
+
+=== Configuring Periodical Flush for metadata Channel ===
+
+Since LTTng Tools v2.2.0 it is possible to configure periodical flush for the metadata channel. To set this, use the checkbox '''Configure metadata channel''' then fill the switch timer interval.
+
+[[Image:images/LTTng2CreateChannelDialogMetadataFlush.png]]
+
+=== Enabling Channels On Domain Level ===
+
+Once a domain is available, channels can be enabled directly using the domain. To enable a channel under an existing domain, select the tree node of the relevant domain and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
+
+[[Image:images/LTTng2CreateChannelOnDomainAction.png]]
+
+The dialog box for enabling channel will open for entering information about the channel to be created. Note that the domain is pre-selected and cannot be changed. Fill the relevant information and press '''Ok'''.
+
+=== Enabling and Disabling Channels ===
+
+To disable one or more enabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the '''Disable Channel''' menu item of the context-sensitive menu.
+
+[[Image:images/LTTng2DisableChannelAction.png]]
+
+Upon successful operation, the selected channels will be '''DISABLED''' and the icons for the channels will be updated.
+
+To enable one or more disabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the '''Enable Channel''' menu item of the context-sensitive menu.
+
+[[Image:images/LTTng2EnableChannelAction.png]]
+
+Upon successful operation, the selected channels will be '''ENABLED''' and the icons for the channels will be updated.
+
+=== Enabling Events - General ===
+
+Enabling events can be done using different levels in the tree node. It can be done on the session, domain level and channel level. For the case of session or domain, i.e. when no specific channels is assigned then enabling of events is done on the default channel with the name '''channel0''' which created, if not already exists, by the LTTng tracer control on the server side.
+
+=== Enabling Kernel Events On Session Level ===
+
+To enable events, select the tree node of the relevant session and press the right mouse button. Then select the '''Enable Event (default channel)...''' button of the context-sensitive menu.
+
+[[Image:images/LTTng2EventOnSessionAction.png]]
+
+A dialog box will open for entering information about events to be enabled.
+
+[[Image:images/LTTng2EventOnSessionDialog.png]]
+
+By default the domain '''Kernel''' is selected and the kernel specific data sections are created. From this dialog box kernel '''Tracepoint''' events, '''System calls (Syscall)''', a '''Dynamic Probe''' or a '''Dynamic Function entry/return''' probe can be enabled. Note that events of one of these types at a time can be enabled.
+
+To enable '''Tracepoint''' events, first select the corresponding '''Select''' button, then select either all tracepoins (select '''All''') or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press '''Ok'''.
+
+[[Image:images/LTTng2TracepointEventsDialog.png]]
+
+Upon successful operation, the domain '''Kernel''' will be created in the tree (if neccessary), the default channel with name "channel0" will be added under the domain (if necessary) as well as all requested events of type '''TRACEPOINT''' under the channel. The channel and events will be '''ENABLED'''.
+
+[[Image:images/LTTng2EnabledKernelTracepoints.png]]
+
+To enable all '''Syscalls''', select the corresponding '''Select''' button and press '''Ok'''.
+
+[[Image:images/LTTng2SyscallsDialog.png]]
+
+Upon successful operation, the event with the name '''syscalls''' and event type '''SYSCALL''' will be added under the default channel (channel0). If necessary the domain '''Kernel''' and the channel '''channel0''' will be created.
+
+[[Image:images/LTTng2EnabledKernelSyscalls.png]]
+
+To enable a '''Dynamic Probe''' event, select the corresponding '''Select''' button, fill the '''Event Name''' and '''Probe''' fields and press '''Ok'''. Note that the probe can be an address, symbol or a symbol+offset where the address and offset can be octal (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...).
+
+[[Image:images/LTTng2ProbeEventDialog.png]]
+
+Upon successful operation, the dynamic probe event with the given name and event type '''PROBE''' will be added under the default channel (channel0). If necessary the domain '''Kernel''' and the channel '''channel0''' will be created.
+
+[[Image:images/LTTng2EnabledKernelProbeEvent.png]]
+
+To enable a '''Dynamic Function entry/return Probe''' event, select the corresponding '''Select''' button, fill the '''Event Name''' and '''Function''' fields and press '''Ok'''. Note that the funtion probe can be an address, symbol or a symbol+offset where the address and offset can be octal (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...).
+
+[[Image:images/LTTng2FunctionEventDialog.png]]
+
+Upon successful operation, the dynamic function probe event with the given name and event type '''PROBE''' will be added under the default channel (channel0). If necessary the domain '''Kernel''' and the channel '''channel0''' will be created.
+
+[[Image:images/LTTng2EnabledFunctionProbeEvent.png]]
+
+=== Enabling UST Events On Session Level ===
+
+For enabling UST events, first open the enable events dialog as described in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]] and select domain '''UST'''.
+
+To enable '''Tracepoint''' events, first select the corresponding '''Select''' button, then select either all tracepoins (select '''All''') or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press '''Ok'''.
+
+[[Image:images/LTTng2UstTracepointEventsDialog.png]]
+
+Upon successful operation, the domain '''UST global''' will be created in the tree (if neccessary), the default channel with name "channel0" will be added under the domain (if necessary) as well as all requested events under the channel. The channel and events will be '''ENABLED'''. Note that for the case that '''All''' tracepoints were selected the wildcard '''*''' is used which will be shown in the Control View as below.
+
+[[Image:images/LTTng2EnabledAllUstTracepoints.png]]
+
+For UST it is possible to enable '''Tracepoint''' events using a wildcard. To enable '''Tracepoint''' events with a wildcard, select first the corresponding '''Select''' button, fill the '''Wildcard''' field and press '''Ok'''.
+
+[[Image:images/LTTng2UstWildcardEventsDialog.png]]
+
+Upon successful operation, the event with the given wildcard and event type '''TRACEPOINT''' will be added under the default channel (channel0). If necessary the domain '''UST global''' and the channel '''channel0''' will be created.
+
+[[Image:images/LTTng2EnabledUstWildcardEvents.png]]
+
+For UST it is possible to enable '''Tracepoint''' events using log levels. To enable '''Tracepoint''' events using log levels, select first the corresponding '''Select''' button, select a log level from the drop down menu, fill in the relevant information (see below) and press '''Ok'''.
+
+* '''Event Name''': Name to display
+* '''loglevel''': To specify if a range of log levels (0 to selected log level) shall be configured
+* '''loglevel-only''': To specify that only the specified log level shall be configured
+
+[[Image:images/LTTng2UstLoglevelEventsDialog.png]]
+
+Upon successful operation, the event with the given event name and event type '''TRACEPOINT''' will be added under the default channel (channel0). If necessary the domain '''UST global''' and the channel '''channel0''' will be created.
+
+[[Image:images/LTTng2EnabledUstLoglevelEvents.png]]
+
+=== Enabling Events On Domain Level ===
+
+Kernel events can also be enabled on the domain level. For that select the relevant domain tree node, click the right mouse button and the select '''Enable Event (default channel)...'''. A new dialog box will open for providing information about the events to be enabled. Depending on the domain, '''Kernel''' or '''UST global''', the domain specifc fields are shown and the domain selector is preselected and read-only.
+
+[[Image:images/LTTng2EventOnDomainAction.png]]
+
+To enable events for domain '''Kernel''' follow the instructions in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]], for domain '''UST global''', see section [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]].
+The events will be add to the default channel '''channel0'''. This channel will be created by on the server side if neccessary.
+
+=== Enabling Events On Channel Level ===
+
+Kernel events can also be enabled on the channel level. If necessary, create a channel as described in sections [[#Enabling Channels On Session Level | Enabling Channels On Session Level]] or [[#Enabling Channels On Domain Level | Enabling Channels On Domain Level]].
+
+Then select the relevant channel tree node, click the right mouse button and the select '''Enable Event...'''. A new dialog box will open for providing information about the events to be enabled. Depending on the domain, '''Kernel''' or '''UST global''', the domain specifc fields are shown and the domain selector is preselected and read-only.
+
+[[Image:images/LTTng2EventOnChannelAction.png]]
+
+To enable events for domain '''Kernel''' follow the instructions in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]], for domain '''UST global''' [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]].
+
+When enabling events on the channel level, the events will be add to the selected channel.
+
+=== Enabling and Disabling Events ===
+
+To disable one or more enabled events, select the tree nodes of the relevant events and click the right mouse button. Then select '''Disable Event''' menu item in the context-sensitive menu.
+
+[[Image:images/LTTng2DisableEventAction.png]]
+
+Upon successful operation, the selected events will be '''DISABLED''' and the icons for these events will be updated.
+
+To enable one or more disabled events, select the tree nodes of the relevant events and press the right mouse button. Then select the '''Enable Event''' menu item of the context-sensitive menu.
+
+[[Image:images/LTTng2EnableEventAction.png]]
+
+Upon successful operation, the selected events will be '''ENABLED''' and the icons for these events will be updated.
+
+'''Note''': There is currently a limitation for kernel event of type '''SYSCALL'''. This kernel event can not be disabled. An error will appear when trying to disable this type of event. A work-around for that is to have the syscall event in a separate channel and disable the channel instead of the event.
+
+=== Enabling Tracepoint Events From Provider ===
+
+It is possible to enable events of type '''Tracepoint''' directly from the providers and assign the enabled event to a session and channel. Before doing that a session has to be created as described in section [[#Creating a Tracing Session | Creating a Tracing Session]]. Also, if other than default channel '''channel0''' is required, create a channel as described in sections [[#Enabling Channels On Session Level | Enabling Channels On Session Level]] or [[#Enabling Channels On Domain Level | Enabling Channels On Domain Level]].
+
+To assign tracepoint events to a session and channel, select the events to be enabled under the provider (e.g. provider '''Kernel'''), click right mouse button and then select '''Enable Event...''' menu item from the context sensitive menu.
+
+[[Image:images/LTTng2AssignEventAction.png]]
+
+A new display will open for defining the session and channel.
+
+[[Image:images/LTTng2AssignEventDialog.png]]
+
+Select a session from the '''Session List''' drop-down menu, a channel from the '''Channel List''' drop-down menu and the press '''Ok'''. Upon successful operation, the selected events will be added to the selected session and channel of the domain that the selected provider belongs to. In case that there was no channel available, the domain and the default channel '''channel0''' will be created for corresponding session. The newly added events will be '''ENABLED'''.
+
+[[Image:images/LTTng2AssignedEvents.png]]
+
+=== Configuring Filter Expression On UST Event Fields ===
+
+Since LTTng Tools v2.1.0 it is possible to configure a filter expression on UST event fields. To configure a filter expression on UST event fields, open the enable event dialog as described in chapters [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]], [[#Enabling Events On Domain Level | Enabling Events On Domain Level]] or [[#Enabling Events On Channel Level | Enabling Events On Channel Level]], select UST if needed, select the relevant '''Tracepoint''' event(s) and enter the filter expression in the '''Filter Expression''' text field.
+
+[[Image:images/LTTng2EnableEventWithFilter.png]]
+
+Alternatively, open the dialog box for assigning events to a session and channel described in [[#Enabling Tracepoint Events From Provider | Enabling Tracepoint Events From Provider]] (for UST providers) and enter the filter expression in the '''Filter Expression''' text field.
+
+[[Image:images/LTTng2AssignEventDialogWithFilter.png]]
+
+For the syntax of the filter expression refer to the '''LTTng Tracer Control Command Line Tool User Manual''' of chapter [[#References |References]].
+
+=== Adding Contexts to Channels and Events of a Domain ===
+
+It is possible to add contexts to channels and events. Adding contexts on channels and events from the domain level, will enable the specified contexts to all channels of the domain and all their events. To add contexts on the domain level, select a domain, click right mouse button on a domain tree node (e.g. provider '''Kernel''') and select the menu item '''Add Context...''' from the context-sensitive menu.
+
+[[Image:images/LTTng2AddContextOnDomainAction.png]]
+
+A new display will open for selecting one or more contexts to add.
+
+[[Image:images/LTTng2AddContextDialog.png]]
+
+The tree shows all available context that can be added. Select one or more context and the press '''Ok'''. Upon successful operation, the selected context will be added to all channels and their events of the selected domain.
+
+'''Note''': The LTTng UST tracer only supports contexts '''procname''', '''pthread_id''', '''vpid''' '''vtid'''. Adding any other contexts in the UST domina will fail.
+
+=== Adding Contexts to All Events of a Channel ===
+
+Adding contexts on channels and events from the channel level, will enable the specified contexts to all events of the selected channel. To add contexts on the channel level, select a channel, click right mouse button on a channel tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
+
+[[Image:images/LTTng2AddContextOnChannelAction.png]]
+
+A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter [[#Adding Contexts to Channels and Events of a Domain | Adding Contexts to Channels and Events of a Domain]]. Upon successful operation, the selected context will be added to all channels and their events of the selected domain. '''Note''' that the LTTng 2.0 tracer control on the remote host doesn't provide a way to retrieve added contexts. Hence it's not possible to display the context information in the GUI.
+
+=== Adding Contexts to an Event of a Specific Channel ===
+
+Adding contexts to an event of a channel is only available in LTTng Tools versions v2.0.0-2.1.x. The menu option won't be visible for LTTng Tools version v2.2.0 or later. To add contexts on an event select an event of a channel, click right mouse button on the corresponding event tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
+
+[[Image:images/LTTng2AddContextToEventsAction.png]]
+
+A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter [[#Adding Contexts to Channels and Events of a Domain | Adding Contexts to Channels and Events of a Domain]]. Upon successful operation, the selected context will be added to the selected event.
+
+=== Start Tracing ===
+
+To start tracing, select one or more sessions to start in the Control View and press the '''Start''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Start''' menu item.
+
+[[Image:images/LTTng2StartTracingAction.png]]
+
+Upon successful operation, the tracing session will be '''ACTIVE''' and the icon of the session will be updated.
+
+=== Recording a Snapshot ===
+
+LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After creating a snapshot session (see [[#Creating a Snapshot Tracing Session | Creating a Snapshot Tracing Session]]) and starting tracing (see [[#Start Tracing | Start Tracing]]) it possible to record snapshots. To record a snapshot select one or more sessions and press the '''Record Snapshot''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Recored Snapshot''' menu item.
+
+[[Image:images/LTTng2RecordSnapshotAction.png]]
+
+This action can be executed many times. It is possible to import the recorded snpshots to a tracing project. The trace session might be '''ACTIVE''' or '''INACTIVE''' for that. Refer to section [[#Importing Session Traces to a Tracing Project | Importing Session Traces to a Tracing Project]] on how to import a trace to a tracing project.
+
+=== Stop Tracing ===
+
+To stop tracing, select one or more sessions to stop in the Control View and press the '''Stop''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Stop''' menu item.
+
+[[Image:images/LTTng2StopTracingAction.png]]
+
+Upon successful operation, the tracing session will be '''INACTIVE''' and the icon of the session will be updated.
+
+=== Destroying a Tracing Session ===
+
+To destroy a tracing session, select one or more sessions to destroy in the Control View and press the '''Destroy''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Destroy...''' menu item. Note that the session has to be '''INACTIVE''' for this operation.
+
+[[Image:images/LTTng2DestroySessionAction.png]]
+
+A confirmation dialog box will open. Click on '''Ok''' to destroy the session otherwise click on '''Cancel'''.
+
+[[Image:images/LTTng2DestroyConfirmationDialog.png]]
+
+Upon successful operation, the tracing session will be destroyed and removed from the tree.
+
+=== Refreshing the Node Information ===
+
+To refresh the remote host information, select any node in the tree of the Control View and press the '''Refresh''' button. Alternatively, click the right mouse button on any tree node. A context-sensitive menu will show. Then select the '''Refresh''' menu item.
+
+[[Image:images/LTTng2RefreshAction.png]]
+
+Upon successful operation, the tree in the Control View will be refreshed with the remote host configuration.
+
+=== Quantifing LTTng overhead (Calibrate) ===
+
+The LTTng calibrate command can be used to find out the combined average overhead of the LTTng tracer and the instrumentation mechanisms used. For now, the only calibration implemented is that of the kernel function
+instrumentation (kretprobes). To run the calibrate command, select the a domain (e.g. '''Kernel'''), click the right mouse button on the domain tree node. A context-sensitive menu will show. Select the '''Calibrate''' menu item.
+
+[[Image:images/LTTng2CalibrateAction.png]]
+
+Upon successful operation, the calibrate command is executed and relevant information is stored in the trace. Note: that the trace has to be active so that to command as any effect.
+
+=== Importing Session Traces to a Tracing Project ===
+
+To import traces from a tracing session, select the relevant session and click on the '''Import''' Button. Alternatively, click the right mouse button on the session tree node and select the menu item '''Import...''' from the context-sensitive menu.
+
+[[Image:images/LTTng2ImportAction.png]]
+
+A new display will open for selecting the traces to import.
+
+[[Image:images/LTTng2ImportDialog.png]]
+
+By default all traces are selected. A default project with the name '''Remote''' is selected which will be created if necessary. Update the list of traces to be imported, if necessary, by selecting and deselecting the relevant traces in the tree viewer. Use buttons '''Select All''' or '''Deselect All''' to select or deselect all traces. Also if needed, change the tracing project from the '''Available Projects''' combo box. Select the Overwrite button ('''Overwrite existing trace without warning''') if required. Then press button '''Ok'''. Upon successful import operation the selected traces will be stored in the '''Traces''' directory of the specified tracing project. The session directory structure as well as the trace names will be preserved in the destination tracing project. For '''Kernel''' traces the trace type '''LTTng Kernel Trace''' and for '''UST''' traces the trace type '''LTTng UST Trace''' will be set. From the '''Project Explorer''' view, the trace can be analyzed further.
+
+'''Note''': If the overwrite button ('''Overwrite existing trace without warning''') was not selected and a trace with the same name of a trace to be imported already exists in the destination directory of the project, then a new confirmation dialog box will open.
+
+[[Image:images/LTTng2ImportOverwriteConfirmationDialog.png]]
+
+To Overwrite select the '''Overwrite''' Button and press '''Ok'''.
+
+If the existing trace should not be overwritten select, then select the '''Rename''' option of the confirmation dialog box above, enter a new name and then press '''Ok'''.
+
+[[Image:images/LTTng2ImportRenameDialog.png]]
+
+=== Importing Network Traces to a Tracing Project ===
+
+Since LTTng Tools v2.1.0 it is possible to store traces over the network. To import network traces, execute the '''Import''' action as described in chapter [[#Importing Session Traces to a Tracing Project | Importing Session Traces to a Tracing Project]]. For network traces the '''Import Trace Wizard''' will be displayed. Follow the instructions in chapter [[#Importing | Importing]] to import the network traces of the current session.
+
+== Properties View ==
+
+The Control View provides property information of selected tree component. Depending on the selected tree component different properties are displayed in the property view. For example, when selecting the node level the property view will be filled as followed:
+
+[[Image:images/LTTng2PropertyView.png]]
+
+'''List of properties''':
+
+* '''Host''' Properties
+** '''Connection Name''': The alias name to be displayed in the Control View.
+** '''Host Name''': The IP address or DNS name of the remote system.
+** '''State''': The state of the connection ('''CONNECTED''', '''CONNECTING''', '''DISCONNNECTING''' or '''DISCONNECTED''').
+* '''Kernel Provider''' Properties
+** '''Provider Name''': The name of the provider.
+* '''UST Provider''' Properties
+** '''Provider Name''': The name of the provider.
+** '''Process ID''': The process ID of the provider.
+* '''Event''' Properties (Provider)
+** '''Event Name''': The name of the event.
+** '''Event Type''': The event type ('''TRACEPOINT''' only).
+** '''Fields''': Shows a list of fields defined for the selected event. (UST only, since support for LTTng Tools v2.1.0)
+** '''Log Level''': The log level of the event.
+* '''Session''' Properties
+** '''Session Name''': The name of the Session.
+** '''Session Path''': The path on the remote host where the traces will be stored. (Not shown for snapshot sessions).
+** '''State''': The state of the session ('''ACTIVE''' or '''INACTIVE''')
+** '''Snapshot ID''': The snapshot ID. (Only shown for snapshot sessions).
+** '''Snapshot Name''': The name of the snapshot output configuration. (Only shown for snapshot sessions).
+** '''Snapshot Path''': The path where the snapshot session is located. (Only shown for snapshot sessions).
+* '''Domain''' Properties
+** '''Domain Name''': The name of the domain.
+** '''Buffer Type''': The buffer type of the domain.
+* '''Channel''' Properties
+** '''Channel Name''': The name of the channel.
+** '''Number of Sub Buffers''': The number of sub-buffers of the channel.
+** '''Output type''': The output type for the trace (e.g. ''splice()'' or ''mmap()'')
+** '''Overwrite Mode''': The channel overwrite mode ('''true''' for overwrite mode, '''false''' for discard)
+** '''Read Timer Interval''': The read timer interval.
+** '''State''': The channel state ('''ENABLED''' or '''DISABLED''')
+** '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
+** '''Switch Timer Interval''': The switch timer interval.
+* '''Event''' Properties (Channel)
+** '''Event Name''': The name of the event.
+** '''Event Type''': The event type ('''TRACEPOINT''', '''SYSCALL''' or '''PROBE''').
+** '''Log Level''': The log level of the event. (For LTTng Tools v2.4.0 or later, '''<=''' prior the log level name will indicate a range of log levels and '''==''' a single log level.)
+** '''State''': The Event state ('''ENABLED''' or '''DISABLED''')
+** '''Filter''': Shows '''with filter''' if a filter expression is configured else property '''Filter''' is omitted. (since support for LTTng Tools v2.1.0)
+
+== LTTng Tracer Control Preferences ==
+
+Serveral LTTng 2.0 tracer control preferences exists which can be configured. To configure these preferences, select '''Window->Preferences''' from the top level menu. The preference display will open. Then select '''Tracing->LTTng Tracer Control Preferences'''. This preferences page allows the user to specify the tracing group of the user and to specify the command execution timeout as well as it allows the user to configure the logging of LTTng 2.0 tracer control commands and results to a file.
+
+[[Image:images/LTTng2Preferences.png]]
+
+To change the tracing group of the user which will be specified on each command line, enter the new group name in the '''Tracing Group''' text field and click button '''OK'''. The default tracing group is '''tracing''' and can be restored by pressing the '''Restore Defaults''' button.
+
+[[Image:images/LTTng2PreferencesGroup.png]]
+
+To configure logging of trace control commands and the corresponding command result to a file, selected the button '''Logging'''. To append to an existing log file, select the '''Append''' button. Deselect the '''Append''' button to overwrite any existing log file. It's possible to specify a verbose level. There are 3 levels with inceasing verbosity from '''Level 1''' to '''Level 3'''. To change the verbosity level, select the relevant level or select '''None'''. If '''None''' is selected only commands and command results are logged. Then press on button '''OK'''. The log file will be stored in the users home directory with the name ''lttng_tracer_control.log''. The name and location cannot be changed. To reset to default preferences, click on the button '''Restore Defaults'''.
+
+[[Image:images/LTTng2PreferencesLogging.png]]
+
+To configure the LTTng command execution timeout, enter a timeout value into the text field '''Command Timeout (in seconds)''' and press on button '''OK'''. To reset to the default value of 15 seconds, click on the button '''Restore Defaults'''.
+
+[[Image:images/LTTng2PreferencesTimeout.png]]
+
+= LTTng Kernel Analysis =
+
+Historically, LTTng was developped to trace the Linux kernel and, over time, a number of kernel-oriented analysis views were developped and organized in a perspective.
+
+This section presents a description of the LTTng Kernel Perspective.
+
+== LTTng Kernel Perspective ==
+
+The '''LTTng Kernel''' perspective is built upon the [[#Tracing_Perspective | Tracing Perspective]], re-organizes them slightly and adds the following views:
+
+* [[#Control_Flow_View | Control Flow View]] - to visualize processes state transitions
+* [[#Resources_View | Resources View]] - to visualize system resources state transitions
+* [[#LTTng_Tracer_Control | LTTng Tracer Control]] - to configure LTTng tracing sessions remotely
+
+[[Image:images/LTTngKernelPerspective.png]]
+
+
+The perspective can be opened from the Eclipse Open Perspective dialog ('''Window > Open Perspective... > Other''').
+
+
+[[Image:images/OpenLTTngKernelPerspective.png]]
+
+== Control Flow View ==
+
+The '''''Control Flow''''' view is a LTTng-specific view that shows per-process events graphically. The LTTng Kernel analysis is executed the first time a LTTng Kernel is opened. After opening the trace, the element '''Control Flow''' is added under the '''LTTng Kernel Analysis''' tree element in the Project Explorer. To open the view, double-click the '''Control Flow''' tree element.
+
+[[Image:images/Cfv_show_view.png]]
+
+Alternatively, select ''Control Flow'' under ''LTTng'' within the ''Show View'' window ('''Window''' -> '''Show View''' -> '''Other...'''):
+
+You should get something like this:
+
+[[Image:images/Cfv_global.png]]
+
+The view is divided into the following important sections: '''process tree and information''', '''control flow''' and the '''toolbar'''.
+
+The following sections provide detailed information for each part of the Control Flow View.
+
+=== Process tree and information ===
+
+Processes are organized as a tree within this view. This way, child and parent processes are easy to identify.
+
+[[Image:images/Cfv_process_tree.png]]
+
+The layout is based on the states computed from the trace events.
+
+A given process may be shown at different places within the tree since the nodes are '''unique (TID, birth time) couples'''. This means that if process B of parent A dies, you'll still see it in the tree. If process A forks process B again, it will be shown as a different node since it won't have the same birth time (and probably not the same TID). This has the advantage that the tree, once loaded, never changes: horizontal scrolling within the [[#Control flow|control flow]] remains possible.
+
+The TID column shows the process node's '''thread ID''' and the PTID column shows its '''parent thread ID''' (nothing is shown if the process has no parent).
+
+=== Control flow ===
+
+This part of the Control Flow View is probably the most interesting one. Using the mouse, you can navigate through the trace (go left, right) and zoom on a specific region to inspect its details.
+
+The colored bars you see represent '''states''' for the associated process node. When a process state changes in time, so does the color. For state '''SYSCALL''' the name of the system call is displayed in the state bar. States colors legend is available through a [[#Toolbar|toolbar button]]:
+
+[[Image:images/Cfv_legend.png]]
+
+This dark yellow is what you'll see most of the time since scheduling puts processes on hold while others run.
+
+The vertical blue line with T1 above it is the '''current selection indicator'''. When a time range is selected, the region between the begin and end time of the selection will be shaded and two lines with T1 and T2 above will be displayed. The time stamps corresponding to T1, T2 and their delta are shown in the status line when the mouse is hovering over the control flow.
+
+Arrows can be displayed that follow the execution of each CPU across processes. The arrows indicate when the scheduler switches from one process to another for a given CPU. The CPU being followed is indicated on the state tooltip. When the scheduler switches to and from the idle process, the arrow skips to the next process which executes on the CPU after the idle process. Note that an appropriate zoom level is required for all arrows to be displayed.
+
+The display of arrows is optional and can be toggled using the '''Hide Arrows''' toolbar button. It is also possible to follow a CPU's execution across state changes and the scheduler's process switching using the '''Follow CPU Forward/Backward''' toolbar buttons.
+
+==== Using the mouse ====
+
+The states flow is usable with the mouse. The following actions are set:
+
+* '''left-click''': select a time or time range begin time
+* '''Shift-left-click''': select a time range end time
+* '''left-drag horizontally''': select a time range or change the time range begin or end time
+* '''middle-drag or Ctrl-left-drag horizontally''': pan left or right
+* '''right-drag horizontally''': [[#Zoom region|zoom region]]
+* '''click on a colored bar''': the associated process node is selected and the current time indicator is moved where the click happened
+* '''mouse wheel up/down''': scroll up or down
+* '''Ctrl-mouse wheel up/down''': zoom in or out
+* '''drag the time ruler horizontally''': zoom in or out with fixed start time
+* '''double-click the time ruler''': reset zoom to full range
+
+When the current time indicator is changed (when clicking in the states flow), all the other views are '''synchronized'''. For example, the [[#LTTng Kernel Events Editor|Events Editor]] will show the event matching the current time indicator. The reverse behaviour is also implemented: selecting an event within the Events View will update the Control Flow View current time indicator.
+
+==== Incomplete regions ====
+
+You'll notice '''small dots''' over the colored bars at some places:
+
+[[Image:images/Cfv_small_dots.png]]
+
+Those dots mean the underlying region is '''incomplete''': there's not enough pixels to view all the events. In other words, you have to zoom in.
+
+When zooming in, small dots start to disappear:
+
+[[Image:images/Cfv_zoom.png]]
+
+When no dots are left, you are viewing '''all the events and states''' within that region.
+
+==== Zoom region ====
+
+To zoom in on a specific region, '''right-click and drag''' in order to draw a time range:
+
+[[Image:images/Cfv_zoom_region.png]]
+
+The states flow horizontal space will only show the selected region.
+
+==== Tooltips ====
+
+Hover the cursor over a colored bar and a '''tooltip''' will pop up:
+
+[[Image:images/Cfv_tooltip.png]]
+
+The tooltip indicates:
+
+* the process name
+* the pointed state name
+* the CPU (if applicable)
+* the system call name (if applicable)
+* the pointed state date and start/stop times
+* the pointed state duration (seconds)
+
+=== Toolbar ===
+
+The Control Flow View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
+
+{|
+| [[Image:images/filter_items.gif]]
+| Show View Filter
+| Opens the process filter dialog
+|-
+| [[Image:images/show_legend.gif]]
+| Show Legend
+| Displays the states legend
+|-
+| [[Image:images/home_nav.gif]]
+| Reset the Time Scale to Default
+| Resets the zoom window to the full range
+|-
+| [[Image:images/prev_event.gif]]
+| Select Previous Event
+| Selects the previous state for the selected process
+|-
+| [[Image:images/next_event.gif]]
+| Select Next Event
+| Selects the next state for the selected process
+|-
+| [[Image:images/prev_menu.gif]]
+| Select Previous Process
+| Selects the previous process
+|-
+| [[Image:images/next_menu.gif]]
+| Select Next Process
+| Selects the next process
+|-
+| [[Image:images/zoomin_nav.gif]]
+| Zoom In
+| Zooms in on the selection by 50%
+|-
+| [[Image:images/zoomout_nav.gif]]
+| Zoom Out
+| Zooms out on the selection by 50%
+|-
+| [[Image:images/hide_arrows.gif]]
+| Hide Arrows
+| Toggles the display of arrows on or off
+|-
+| [[Image:images/follow_arrow_bwd.gif]]
+| Follow CPU Backward
+| Selects the previous state following CPU execution across processes
+|-
+| [[Image:images/follow_arrow_fwd.gif]]
+| Follow CPU Forward
+| Selects the next state following CPU execution across processes
+|}
+
+== Resources View ==
+
+This view is specific to LTTng kernel traces. The LTTng Kernel analysis is executed the first time a LTTng Kernel is opened. After opening the trace, the element '''Resources''' is added under the '''LTTng Kernel Analysis''' tree element of the Project Explorer. To open the view, double-click the '''Resources''' tree element.
+
+Alternatively, go in '''Window''' -> '''Show View''' -> '''Other...''' and select '''LTTng/Resources''' in the list.
+
+[[Image:images/Rv_example.png|Example of resources view with all trace points and syscalls enabled]]
+
+This view shows the state of system resources i.e. if changes occured during the trace either on '''CPUs''', '''IRQs''' or '''soft IRQs''', it will appear in this view. The left side of the view present a list of resources that are affected by at least one event of the trace. The right side illustrate the state in which each resource is at some point in time. For state '''USERMODE''' it also prints the process name in the state bar. For state '''SYSCALL''' the name of the system call is
+displayed in the state region.
+
+Just like other views, according to which trace points and system calls are activated, the content of this view may change from one trace to another.
+
+Each state are represented by one color so it is faster to say what is happening.
+
+[[Image:images/Rv_legend.png|Color for each state]]
+
+To go through the state of a resource, you first have to select the resource and the timestamp that interest you. For the latter, you can pick some time before the interesting part of the trace.
+
+[[Image:images/RV_infobox1.png|Shows the state of an IRQ]]
+
+Then, by selecting '''Next Event''', it will show the next state transition and the event that occured at this time.
+
+[[Image:images/RV_infobox2.png|Shows the next state of the IRQ]]
+
+This view is also synchronized with the others : [[#Histogram_View | Histogram View]], [[#LTTng_Kernel_Events_Editor | Events Editor]], [[#Control_Flow_View | Control Flow View]], etc.
+
+=== Navigation ===
+
+See Control Flow View's '''[[#Using_the_mouse | Using the mouse]]''' and '''[[#Zoom_region | Zoom region]]'''.
+
+=== Incomplete regions ===
+
+See Control Flow View's '''[[#Incomplete_regions | Incomplete regions]]'''.
+
+=== Toolbar ===
+
+The Resources View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
+
+{|
+| [[Image:images/show_legend.gif]]
+| Show Legend
+| Displays the states legend
+|-
+| [[Image:images/home_nav.gif]]
+| Reset the Time Scale to Default
+| Resets the zoom window to the full range
+|-
+| [[Image:images/prev_event.gif]]
+| Select Previous Event
+| Selects the previous state for the selected resource
+|-
+| [[Image:images/next_event.gif]]
+| Select Next Event
+| Selects the next state for the selected resource
+|-
+| [[Image:images/prev_menu.gif]]
+| Select Previous Resource
+| Selects the previous resource
+|-
+| [[Image:images/next_menu.gif]]
+| Select Next Resource
+| Selects the next resource
+|-
+| [[Image:images/zoomin_nav.gif]]
+| Zoom In
+| Zooms in on the selection by 50%
+|-
+| [[Image:images/zoomout_nav.gif]]
+| Zoom Out
+| Zooms out on the selection by 50%
+|}
+
+== LTTng CPU Usage View ==
+
+The CPU Usage analysis and view is specific to LTTng Kernel traces. The CPU usage is derived from a kernel trace as long as the '''sched_switch''' event was enabled during the collection of the trace. This analysis is executed the first time that the CPU Usage view is opened after opening the trace. To open the view, double-click on the '''CPU Usage''' tree element under the '''LTTng Kernel Analysis''' tree element of the Project Explorer.
+
+[[Image:images/LTTng_OpenCpuUsageView.png]]
+
+Now, the CPU Usage view will show:
+
+[[Image:images/LTTng_CpuUsageView.png]]
+
+The view is divided into the following important sections: '''Process Information''' and the '''CPU Usage Chart'''.
+
+
+=== Process Information ===
+The Process Information is displayed on the left side of the view and shows all threads that were executing on all available CPUs in the current time range. For each process, it shows in different columns the thread ID (TID), process name (Process), the average (%) execution time and the actual execution time (Time) during the current time range. It shows all threads that were executing on the CPUs in the current time range.
+
+
+=== CPU Usage Chart ===
+
+The CPU Usage Chart on the right side of the view, plots the total time spent on all CPUs of all processes and the time of the selected process.
+
+
+==== Using the mouse ====
+
+The CPU Usage chart is usable with the mouse. The following actions are set:
+
+* '''left-click''': select a time or time range begin time
+* '''Shift-left-click''': select a time range end time
+* '''left-drag horizontally''': select a time range or change the time range begin or end time
+* '''middle-drag''': pan left or right
+* '''right-drag horizontally''': zoom region
+* '''mouse wheel up/down''': zoom in or out
+
+
+==== Tooltips ====
+
+Hover the cursor over a line of the chart and a tooltip will pop up with the following information:
+* '''time''': current time of mouse position
+* '''Total''': The total CPU usage
+
+
+[[Image:images/LTTng_CpuUsageViewToolTip.png]]
+
+
+== LTTng Kernel Events Editor ==
+
+The LTTng Kernel Events editor '''is''' the plain TMF [[#Events_Editor | Events Editor]], except that it provides its own specialized viewer to replace the standard one. In short, it has exactly the same behaviour but the layout is slightly different:
+
+* '''Timestamp''': the event timestamp
+* '''Channel''': the event channel (data collector)
+* '''Event Type''': the event type (or kernel marker)
+* '''Content''': the raw event content
+
+[[Image:images/LTTng2EventsEditor.png]]
+
+= LTTng-UST Analyses =
+
+The Userspace traces are taken on an application level. With kernel traces, you know what events you will have as the domain is known and cloistered. Userspace traces can contain pretty much anything. Some analyses are offered if certain events are enabled.
+
+== Call Stack View ==
+
+The Call Stack view allows the user to visualize the call stack per thread over time, if the application and trace provide this information.
+
+To open this view go in '''Window''' -> '''Show View''' -> '''Other...''' and select '''Tracing/Call Stack''' in the list. The view shows the call stack information for the currently selected trace. Conversely, you can select a trace and expand it in the '''Project Explorer''' then expand '''LTTng-UST CallStack Analysis''' (the trace must be loaded) and open '''Call Stack'''.
+
+The table on the left-hand side of the view shows the threads and call stack. The function name, depth, entry and exit time and duration are shown for the call stack at the selected time.
+
+Double-clicking on a function entry in the table will zoom the time graph to the selected function's range of execution.
+
+The time graph on the right-hand side of the view shows the call stack state graphically over time. The function name is visible on each call stack event if size permits. The color of each call stack event is randomly assigned based on the function name, allowing for easy identification of repeated calls to the same function.
+
+Clicking on the time graph will set the current time and consequently update the table with the current call stack information.
+
+Shift-clicking on the time graph will select a time range. When the selection is a time range, the begin time is used to update the stack information.
+
+Double-clicking on a call stack event will zoom the time graph to the selected function's range of execution.
+
+Clicking the '''Select Next Event''' or '''Select Previous Event''' or using the left and right arrows will navigate to the next or previous call stack event, and select the function currently at the top of the call stack.
+
+Clicking the '''Import Mapping File''' ([[Image:images/import.gif]]) icon will open a file selection dialog, allowing you to import a text file containing mappings from function addresses to function names. If the callstack provider for the current trace type only provides function addresses, a mapping file will be required to get the function names in the view. See the following sections for an example with LTTng-UST traces.
+
+=== Using the Callstack View with LTTng-UST traces ===
+
+There is support in the LTTng-UST integration plugin to display the callstack of applications traced with the ''liblttng-ust-cyg-profile.so'' library (see the ''liblttng-ust-cyg-profile'' man page for additional information). To do so, you need to:
+
+* Recompile your application with "''-g -finstrument-functions''".
+* Add the ''vtid'' and ''procname'' contexts to your trace session. See the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
+** <pre>lttng add-context -u -t vtid -t procname</pre>
+* Preload the ''liblttng-ust-cyg-profile'' library when running your program:
+** <pre>LD_PRELOAD=/usr/lib/liblttng-ust-cyg-profile.so ./myprogram</pre>
+
+Once you load the resulting trace, making sure it's set to the ''Common Trace Format - LTTng UST Trace'' type, the Callstack View should be populated with the relevant information. However, since GCC's cyg-profile instrumentation only provides function addresses, and not names, an additional step is required to get the function names showing in the view. The following section explains how to do so.
+
+=== Importing a function name mapping file for LTTng-UST traces ===
+
+If you followed the steps in the previous section, you should have a Callstack View populated with function entries and exits. However, the view will display the function addresses instead of names in the intervals, which are not very useful by themselves. To get the actual function names, you need to:
+
+* Generate a mapping file from the binary, using:
+** <pre>nm myprogram > mapping.txt</pre>
+* Click the '''Import Mapping File''' ([[Image:images/import.gif]]) button in the Callstack View, and select the ''mapping.txt'' file that was just created.
+
+The view should now update to display the function names instead. Make sure the binary used for taking the trace is the one used for this step too (otherwise, there is a good chance of the addresses not being the same).
+
+== Memory Usage ==
+
+The Memory Usage view allows the user to visualize the active memory usage per thread over time, if the application and trace provide this information.
+
+The view shows the memory consumption for the currently selected trace.
+
+The time chart plots heap memory usage graphically over time. There is one line per process, unassigned memory usage is mapped to "Other".
+
+In this implementation, the user needs to trace while hooking the ''liblttng-ust-libc-wrapper'' by running ''LD_PRELOAD=liblttng-ust-libc-wrapper.so'' '''<exename>'''. This will add tracepoints to memory allocation and freeing to the heap, NOT shared memory or stack usage. If the contexts '''vtid''' and '''procname''' are enabled, then the view will associate the heap usage to processes. As detailed earlier, to enable the contexts, see the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
+* <pre>lttng add-context -u -t vtid -t procname</pre>
+
+If thread information is available the view will look like this:
+
+[[Image:images/memoryUsage/memory-usage-multithread.png]]
+
+If thread information is not available it will look like this:
+
+[[Image:images/memoryUsage/memory-usage-no-thread-info.png]]
+
+The view allows selection of a specific time by left-clicking on a point in the chart. Left mouse dragging will select a time range. Right mouse dragging on the area will zoom in on that window. Middle mouse dragging will move the display window. Mouse wheel operations will zoom in and out also.
+
+Please note this view will not show shared memory or stack memory usage.
+
+= Trace synchronization =
+
+It is possible to synchronize traces from different machines so that they have the same time reference. Events from the reference trace will have the same timestamps as usual, but the events from traces synchronized with the first one will have their timestamps transformed according to the formula obtained after synchronization.
+
+== Obtain synchronizable traces ==
+
+To synchronize traces from different machines, they need to exchange packets through the network and have events enabled such that the data can be matched from one trace to the other. For now, only TCP packets can be matched between two traces.
+
+LTTng traces that can be synchronized are obtained using one of two methods (both methods are compatible):
+
+=== LTTng-module network tracepoint with complete data ===
+
+The tracepoints '''net_dev_queue''' and '''netif_receive_skb''' will be used for synchronization. Both tracepoints are available in lttng-modules since version 2.2, but they do not contain sufficient data to be used to synchronize traces.
+
+An experimental branch introduces this extra data: lttng-modules will need to be compiled by hand.
+
+Obtain the source code for the experimental lttng-modules
+
+ # git clone git://git.dorsal.polymtl.ca/~gbastien/lttng-modules.git
+ # cd lttng-modules
+
+Checkout the ''net_data_experimental'' branch, compile and install lttng-modules as per the lttng-modules documentation
+
+ # git checkout net_data_experimental
+ # make
+ # sudo make modules_install
+ # sudo depmod -a
+
+This experimental branch adds IP, IPv6 and TCP header data to the tracepoints. Packets received and sent with other protocols do not have this extra header data, but all packets are captured.
+
+=== LTTng-modules addons kernel module with dynamic tracepoints ===
+
+This method adds dynamic instrumentation on TCP packets via extra kernel modules. Only TCP packets are captured.
+
+Obtain the source code, along with lttng-modules
+
+ # git clone https://github.com/giraldeau/lttng-modules.git
+ # cd lttng-modules
+
+Checkout the addons branch, compile and install lttng-modules as per the lttng-modules documentation. The ''make'' command will fail at first with a message about the unset SYSMAP variable. Instructions on how to generate a System.map are mentioned in the error message.
+
+ # git checkout addons
+ # make
+ # (follow the instructions to obtain the System.map file and set the SYSMAP variable)
+ # make
+ # sudo make modules_install
+ # sudo depmod -a
+
+The lttng-addons modules must be inserted manually for the TCP tracepoints to be made available.
+
+ # sudo modprobe lttng-addons
+ # sudo modprobe lttng-probe-addons
+
+The following tracepoints will be available
+
+ # sudo lttng list -k
+ Kernel events:
+ -------------
+ ...
+ inet_sock_create (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_delete (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_clone (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_accept (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_connect (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_local_in (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_local_out (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ ...
+
+The ones used for trace synchronization are '''inet_sock_local_in''' and '''inet_sock_local_out'''.
+
+== Synchronize traces in TMF ==
+
+In order to synchronize traces, create a new experiment and select all traces that need to be synchronized. Right-click on the experiment and select '''Synchronize traces'''. For each trace whose time needs to be transformed, a new trace named as the original but followed by a '_' will be created with the transformed timestamps, and the original trace will be replaced in the experiment. The original trace can still be accessed under the '''Traces''' folder.
+
+[[Image:images/Sync_menu.png|Right-click synchronize traces to perform the trace synchronization]]
+
+When opening the experiment now, all the views will be synchronized. The following screenshot presents the differences in the filtered Control Flow View before and after the time synchronization.
+
+[[Image:images/Sync_cfv.png|Example of Control Flow View before and after trace synchronization]]
+
+Information on the quality of the synchronization, the timestamp transformation formula and some synchronization statistics can be visualized in the '''Synchronization''' view. To open the '''Synchronization''' view, use the Eclipse Show View dialog ('''Window''' -> '''Show View''' -> '''Other...'''). Then select '''Synchronization''' under '''Tracing'''.
+
+[[Image:images/Sync_view.png|Example of Synchronization view]]
+
+= Time offsetting =
+
+The time offsetting feature allows the user to apply a fixed offset to all event timestamps in a trace. It can be used, for example, to adjust the start time of a trace, or to manually align the timestamp of events from different traces.
+
+== Basic mode ==
+
+If the time offset to apply is known, it can be applied directly to the trace. In the '''Project Explorer''' view, select a trace, right-click and select '''Apply Time Offset...'''. It is also possible to select multiple traces, experiments or trace folders. All contained traces will be selected.
+
+[[Image:images/TimeOffsetApply.png|Apply Time Offset menu]]
+
+The dialog opens, in '''Basic''' mode.
+
+[[Image:images/TimeOffsetBasicDialog.png|Apply Time Offset dialog - Basic mode]]
+
+Enter a time offset to apply in the '''Offset in seconds''' column, with or without decimals. Then press the '''OK''' button.
+
+[[Image:images/TimeOffsetBasicDialogFilled.png|Apply Time Offset dialog - Basic mode - filled]]
+
+The time offset is applied to the trace and can be seen in the '''time offset''' property in the '''Properties''' view when the trace is selected.
+
+The applied time offset is added to any time offset or time transformation formula currently set for the trace, and the resulting offset replaces any previous setting.
+
+== Advanced mode ==
+
+The time offset can also be computed using selected trace events or manually entered timestamps. After selecting one or more traces in the '''Project Explorer''' view, right-click and select '''Apply Time Offset...'''. In the opened dialog, select the '''Advanced''' button.
+
+[[Image:images/TimeOffsetAdvancedDialog.png|Apply Time Offset dialog - Advanced mode]]
+
+Double-clicking a trace name will open the trace in an editor. The '''Reference Time''' will be set to the trace start time. Selecting any event in the trace editor will set the '''Reference Time''' for that trace to the event's timestamp.
+
+Selecting an event or a time in any view or editor that supports time synchronization will set the '''Target Time''' for every trace in the dialog.
+
+Pressing the '''<<''' button will compute the time offset that should be applied in order to make the reference time align to the target time, provided that both fields are set.
+
+The '''Reference Time''', '''Target Time''' and '''Offset in seconds''' fields can also be edited and entered manually.
+
+To synchronize two events from different traces, first select an event in the trace to which the time offset should be applied, which will set its '''Reference Time''' field.
+
+[[Image:images/TimeOffsetAdvancedSetReference.png|Apply Time Offset dialog - Set Reference Time]]
+
+Then select a corresponding event in the second trace, which will set the '''Target Time''' field for the first trace.
+
+[[Image:images/TimeOffsetAdvancedSetTarget.png|Apply Time Offset dialog - Set Target Time]]
+
+Finally, press the '''<<''' button, which will automatically compute the time offset that should be applied in order to make the first event's timestamp align to the second event's timestamp.
+
+[[Image:images/TimeOffsetAdvancedComputeOffset.png|Apply Time Offset dialog - Compute Offset]]
+
+Then press the '''OK''' button. The time offset is applied to the trace and can be seen in the '''time offset''' property in the '''Properties''' view when the trace is selected.
+
+The applied time offset is added to any time offset or time transformation formula currently set for the trace, and the resulting offset replaces any previous setting.
+
+[[Image:images/TimeOffsetProperty.png|Time Offset - Properties view]]
+
+== Clearing time offset ==
+
+The time offset previously applied can be cleared to reset the trace to its original timestamps. In the '''Project Explorer''' view, select a trace, right-click and select '''Clear Time Offset'''. It is also possible to select multiple traces, experiments or trace folders. All contained traces will be affected.
+
+The time offset or any time transformation formula will be deleted.
+
+= Timestamp formatting =
+
+Most views that show timestamps are displayed in the same time format. The unified timestamp format can be changed in the Preferences page. To get to that page, click on '''Window''' -> '''Preferences''' -> '''Tracing''' -> '''Time Format'''. Then a window will show the time format preferences.
+
+[[Image:images/TmfTimestampFormatPage.png]]
+
+The preference page has several subsections:
+
+* '''Current Format''' a format string generated by the page
+* '''Sample Display''' an example of a timestamp formatted with the '''Current Format''' string.
+* '''Time Zone''' the time zone to use when displaying the time. The value '''Local time''' corresponds to the local, system-configured, time zone.
+* '''Data and Time format''' how to format the date (days/months/years) and the time (hours/minutes/seconds)
+* '''Sub-second format''' how much precision is shown for the sub-second units
+* '''Date delimiter''' the character used to delimit the date units such as months and years
+* '''Time delimiter''' the character to separate super-second time units such as seconds and minutes
+* '''Sub-Second Delimiter''' the character to separate the sub-second groups such as milliseconds and nanoseconds
+* '''Restore Defaults''' restores the system settings
+* '''Apply''' apply changes
+
+This will update all the displayed timestamps.
+
+= Data driven analysis =
+
+It is possible to define custom trace analyses and a way to view them in an XML format. These kind of analyses allow doing more with the trace data than what the default analyses shipped with TMF offer. It can be customized to a specific problem, and fine-tuned to show exactly what you're looking for.
+
+== Importing an XML file containing analysis ==
+
+If you already have an XML file defining state providers and/or views, you can import it in your TMF workspace by right-clicking on the ''Traces'' or ''Experiments'' folder and selecting ''Import XML Analysis''.
+
+[[Image:images/import_XML_analysis.png| Import XML analysis menu]]
+
+You will be prompted to select the file. It will be validated before importing it and if successful, the new analysis and views will be shown under the traces for which they apply. You will need to close any already opened traces and re-open them before the new analysis can be executed.
+
+Right now, there is no way to "unimport" analyses from within the application. A UI to manage the imported analyses is currently being worked on. In the meantime, you can navigate to your workspace directory, and delete the files in .metadata/.plugins/org.eclipse.linuxtools.tmf.analysis.xml.core/xml_files .
+
+== Defining XML components ==
+
+To define XML components, you need to create a new XML file and use the XSD that comes with the XML plugin.
+
+''For now, the XSD is only available through the source code in org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd''.
+
+An empty file, with no content yet would look like this:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:noNamespaceSchemaLocation="xmlDefinition.xsd">
+
+</tmfxml>
+</pre>
+
+== Defining an XML state provider ==
+
+The state system is a component of TMF which can track the states of different elements of the system over the duration of a trace. To build this state system, events have to go chronologically through a state provider, which defines what changes are caused by the event to the system.
+
+The state system obtained by the state provider can then be used to populate data-driven views without having to re-read the trace, or to query specific timestamps in the trace without needing to access the trace file.
+
+=== Definitions and example ===
+
+Before we start, we'll define a few terms used in the following sections. The interested reader should read the [[Developer-Guide|Tmf Developer Guide]] for more complete description of the state system and state providers.
+
+* The '''state system''' can be viewed as a model of the system, where the different elements (attributes) can be seen as a tree, and their evolution (states) is tracked through time.
+
+* '''Attribute''': An attribute is the smallest element of the model that can be in any particular state. Since many attributes may have the same name, each attribute is represented by its full path in the attribute tree.
+
+* '''State''': A state is a value assigned to an attribute at a given time. Each model has its own state values.
+
+* '''Attribute tree''': Elements in the model can be placed in a tree-like structure, for logical grouping. Each element in the tree can have both children and a state. Also, the tree is just a logical structure, all elements may be top-level elements.
+
+* '''State history''': Whereas the attribute tree may be seen as the first dimension of the state system, the state history is the second dimension, over time. It tracks the intervals at which an attribute was in a given state.
+
+In the following sections, we'll use an example trace with the following events:
+
+* start(number): A new task with ID 'number' just started.
+* execute(number, fct_name): The task with ID 'number' is executing a critical section named 'fct_name'.
+* wait(number): The task with ID 'number' cannot execute a critical section and needs to wait for it.
+* exec_end(fct_name): A task finished executing the critical section named 'fct_name'.
+* stop(number): The task with ID 'number' has just finished.
+
+=== Determining the state system structure ===
+
+The first thing to do is to determine the attribute tree we'll use to represent the model of the system. The attribute tree is like a file system with directories and files, where files are logically gathered in the same parent directory. There is no one good way to build a tree, the logic will depend on the situation and on the person defining it.
+
+The generated state system may be used later on to populate views, so attributes of the tree could be grouped in such a way as to make it easy to reach them with a simple path. The view will then be more simple.
+
+In our example case, we'll want to track the status of each task and, for each critical section, which task is running them.
+
+<pre>
+|- Tasks
+| |- 1
+| |- 2
+| ...
+|- Critical section
+ |- Crit_sect1
+ |- Crit_sect2
+ ...
+</pre>
+
+Then we determine how each event will affect the state of the attributes. But first, let's ask ourselves what values should each state take.
+
+Let's see with the tree:
+
+<pre>
+|- Tasks -> Empty
+| |- 1 -> Each task can be in one of
+| |- 2 RUNNING, CRITICAL, WAITING
+| ...
+|- Critical section -> Empty
+ |- Crit_sect1 -> Each critical section will hold the currently running task number
+ |- Crit_sect2
+ ...
+</pre>
+
+Then we determine how each event will affect the state of the attributes. In the attribute paths below, elements in {} are values coming from the trace event, while strings are constants. For the sake of simplicity, we'll say "update attribute", but if an attribute does not exist, it will be created.
+
+* start(number): Update state value of attribute "Tasks/{number}" to "RUNNING".
+* execute(number, fct_name): Update state value of attribute "Tasks/{number}" to "CRITICAL" and Update attribute "Critical section/{fct_name}" to "{number}".
+* wait(number): Update state value of attribute "Tasks/{number}" to "WAITING".
+* exec_end(fct_name): Update state value of attribute "Tasks/{valueOf Critical section/{fct_name}}" to RUNNING and update "Critical section/{fct_name}" to null.
+* stop(number): Update state value of attribute "Tasks/{number}" to null.
+
+=== Writing the XML state provider ===
+
+Once the model is done at a high level, it is time to translate it to an XML data-driven analysis. For details on how to use each XML element, refer to the documentation available in the XSD files. Some elements will be commented on below.
+
+First define the state provider element.
+
+The "version" attribute indicates which version of the state system is defined here. Once a state provider has been defined for a trace type, it will typically be used by a team of people and it may be modified over time. This version number should be bumped each time a new version of the state provider is published. This will force a rebuild of any existing state histories (if applicable) whose version number is different from the current one.
+
+The "id" attribute uniquely identifies this state provider, and the analysis that will contain it.
+
+<pre>
+<stateProvider version="0" id="my.test.state.provider">
+</pre>
+
+Optional header information can be added to the state provider. A "traceType" should be defined to tell TMF which trace type this analysis will apply to. If no tracetype is specified, the analysis will appear under every trace. A "label" can optionally be added to have a more user-friendly name for the analysis.
+
+<pre>
+<head>
+ <traceType id="my.trace.id" />
+ <label value="My test analysis" />
+</head>
+</pre>
+
+If pre-defined values will be used in the state provider, they must be defined before the state providers. They can then be referred to in the state changes by name, preceded by the '$' sign. It is not necessary to use pre-defined values, the state change can use values like (100, 101, 102) directly.
+
+<pre>
+<definedValue name="RUNNING" value="100" />
+<definedValue name="CRITICAL" value="101" />
+<definedValue name="WAITING" value="102" />
+</pre>
+
+The following event handler shows what to do with the event named ''start''. It causes one state change. The sequence of '''stateAttribute''' elements represents the path to the attribute in the attribute tree, each element being one level of the tree. The '''stateValue''' indicates which value to assign to the attribute at the given path. The "$RUNNING" value means it will use the predefined value named RUNNING above.
+
+Suppose the actual event is ''start(3)''. The result of this state change is that at the time of the event, the state system attribute "Tasks/3" will have value 100.
+
+<pre>
+<eventHandler eventName="start">
+ <stateChange>
+ <stateAttribute type="constant" value="Tasks" />
+ <stateAttribute type="eventField" value="number" />
+ <stateValue type="int" value="$RUNNING" />
+ </stateChange>
+</eventHandler>
+</pre>
+
+The full XML file for the example above would look like this:
+
+<pre>
+<?xml version="1.0" encoding="UTF-8"?>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
+ <stateProvider version="0" id="my.test.state.provider">
+ <head>
+ <traceType id="my.trace.id" />
+ <label value="My test analysis" />
+ </head>
+
+ <definedValue name="RUNNING" value="100" />
+ <definedValue name="CRITICAL" value="101" />
+ <definedValue name="WAITING" value="102" />
+
+ <eventHandler eventName="start">
+ <stateChange>
+ <stateAttribute type="constant" value="Tasks" />
+ <stateAttribute type="eventField" value="number" />
+ <stateValue type="int" value="$RUNNING" />
+ </stateChange>
+ </eventHandler>
+ <eventHandler eventName="execute">
+ <stateChange>
+ <stateAttribute type="constant" value="Tasks" />
+ <stateAttribute type="eventField" value="number" />
+ <stateValue type="int" value="$CRITICAL" />
+ </stateChange>
+ <stateChange>
+ <stateAttribute type="constant" value="Critical section" />
+ <stateAttribute type="eventField" value="fct_name" />
+ <stateValue type="eventField" value="number" />
+ </stateChange>
+ </eventHandler>
+ <eventHandler eventName="wait">
+ <stateChange>
+ <stateAttribute type="constant" value="Tasks" />
+ <stateAttribute type="eventField" value="number" />
+ <stateValue type="int" value="$WAITING" />
+ </stateChange>
+ </eventHandler>
+ <eventHandler eventName="exec_end">
+ <stateChange>
+ <stateAttribute type="constant" value="Tasks" />
+ <stateAttribute type="query">
+ <stateAttribute type="constant" value="Critical section" />
+ <stateAttribute type="eventField" value="fct_name" />
+ </stateAttribute>
+ <stateValue type="int" value="$RUNNING" />
+ </stateChange>
+ <stateChange>
+ <stateAttribute type="constant" value="Critical section" />
+ <stateAttribute type="eventField" value="fct_name" />
+ <stateValue type="null" />
+ </stateChange>
+ </eventHandler>
+ <eventHandler eventName="stop">
+ <stateChange>
+ <stateAttribute type="constant" value="Tasks" />
+ <stateAttribute type="eventField" value="number" />
+ <stateValue type="null" />
+ </stateChange>
+ </eventHandler>
+ </stateProvider>
+</tmfxml>
+</pre>
+
+=== Debugging the XML state provider ===
+
+To debug the state system that was generated by the XML state provider, one could use the [[#State System Explorer View | State System Explorer View]], along with the events editor. By selecting an event, you can see what changes this event caused and the states of other attributes at the time.
+
+If there are corrections to make, you may modify the XML state provider file, and re-import it. To re-run the analysis, you must first delete the supplementary files by right-clicking on your trace, and selecting ''Delete supplementary files...''. Check you analysis's .ht file, so that the analysis will be run again when the trace is reopened. The supplementary file deletion will have closed the trace, so it needs to be opened again to use the newly imported analysis file.
+
+If modifications are made to the XML state provider after it has been "published", the '''version''' attribute of the '''xmlStateProvider''' element should be updated. This avoids having to delete each trace's supplementary file manually. If the saved state system used a previous version, it will automatically be rebuilt from the XML file.
+
+== Defining an XML time graph view ==
+
+A time graph view is a view divided in two, with a tree viewer on the left showing information on the different entries to display and a Gantt-like viewer on the right, showing the state of the entries over time. The [[#Control_Flow_View | Control Flow View]] is an example of a time graph view.
+
+Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
+
+In the example above, suppose we want to display the status for each task. In the state system, it means the path of the entries to display is "Tasks/*". The attribute whose value should be shown in the Gantt chart is the entry attribute itself. So the XML to display these entries would be as such:
+
+<pre>
+<entry path="Tasks/*">
+ <display type="self" />
+</entry>
+</pre>
+
+But first, the view has to be declared. It has an ID, to uniquely identify this view among all the available XML files.
+
+<pre>
+<timeGraphView id="my.test.time.graph.view">
+</pre>
+
+Optional header information can be added to the view. '''analysis''' elements will associate the view only to the analysis identified by the "id" attribute. It can be either the ID of the state provider, like in this case, or the analysis ID of any analysis defined in Java. If no analysis is specified, the view will appear under every analysis with a state system. The '''label''' element allows to give a more user-friendly name to the view. The label does not have to be unique. As long as the ID is unique, views for different analyses can use the same name.
+
+<pre>
+<head>
+ <analysis id="my.test.state.provider" />
+ <label value="My Sample XML View" />
+</head>
+</pre>
+
+Also, if the values of the attributes to display are known, they can be defined, along with a text to explain them and a color to draw them with. Note that the values are the same as defined in the state provider, but the name does not have to be the same. While in the state provider, a simple constant string makes sense to use in state changes. But in the view, the name will appear in the legend, so a user-friendly text is more appropriate.
+
+<pre>
+<definedValue name="The process is running" value="100" color="#118811" />
+<definedValue name="Critical section" value="101" color="#881111" />
+<definedValue name="Waiting for critical section" value="102" color="#AEB522" />
+</pre>
+
+Here is the full XML for the time graph view:
+
+<pre>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
+ <timeGraphView id="my.test.time.graph.view">
+ <head>
+ <analysis id="my.test.state.provider" />
+ <label value="My Sample XML View" />
+ </head>
+
+ <definedValue name="The process is running" value="100" color="#118811" />
+ <definedValue name="Critical section" value="101" color="#881111" />
+ <definedValue name="Waiting for critical section" value="102" color="#AEB522" />
+
+ <entry path="Tasks/*">
+ <display type="self" />
+ </entry>
+ </timeGraphView>
+</tmfxml>
+</pre>
+
+The following screenshot shows the result of the preceding example on a test trace. The trace used, as well as the XML file are available [http://secretaire.dorsal.polymtl.ca/~gbastien/Xml4Traces/XML_documentation_example.tar.gz here].
+
+[[Image:images/Xml_analysis_screenshot.png| XML analysis with view]]
+
+== Defining an XML XY chart ==
+
+An XY chart displays series as a set of numerical values over time. The X-axis represents the time and is synchronized with the trace's current time range. The Y-axis can be any numerical value.
+
+Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
+
+We will use the LTTng Kernel Analysis on LTTng kernel traces to show an example XY chart. In this state system, the status of each CPU is a numerical value. We will display this value as the Y axis of the series. There will be one series per CPU. The XML to display these entries would be as such:
+
+<pre>
+<entry path="CPUs/*">
+ <display type="constant" value="Status" />
+ <name type="self" />
+</entry>
+</pre>
+
+But first, the view has to be declared. It has an ID, to uniquely identify this view among all the available XML files.
+
+<pre>
+<xyView id="my.test.xy.chart.view">
+</pre>
+
+Like for the time graph views, optional header information can be added to the view. '''analysis''' elements will associate the view only to the analysis identified by the "id" attribute. It can be either the ID of the state provider, like in this case, or the analysis ID of any analysis defined in Java. If no analysis is specified, the view will appear under every analysis with a state system. The '''label''' element allows to give a more user-friendly name to the view. The label does not have to be unique. As long as the ID is unique, views for different analyses can use the same name.
+
+<pre>
+<head>
+ <analysis id="org.eclipse.linuxtools.lttng2.kernel.analysis" />
+ <label value="CPU status XY view" />
+</head>
+</pre>
+
+Here is the full XML for the XY Chart that displays the CPU status over time of an LTTng Kernel Trace:
+
+<pre>
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
+ <xyView id="my.test.xy.chart.view">
+ <head>
+ <analysis id="org.eclipse.linuxtools.lttng2.kernel.analysis" />
+ <label value="CPU status XY view" />
+ </head>
+
+ <entry path="CPUs/*">
+ <display type="constant" value="Status" />
+ <name type="self" />
+ </entry>
+ </xyView>
+</tmfxml>
+</pre>
+
+The following screenshot shows the result of the preceding example on a LTTng Kernel Trace.
+
+[[Image:images/XML_xy_chart.png| XML XY chart]]
+
+= Limitations =
+
+* When parsing text traces, the timestamps are assumed to be in the local time zone. This means that when combining it to CTF binary traces, there could be offsets by a few hours depending on where the traces were taken and where they were read.
+* LTTng Tools v2.1.0 introduced the command line options ''--no-consumer'' and ''--disable-consumer'' for session creation as well as the commands ''enable-consumer'' and ''disable-consumer''. The LTTng Tracer Control in Eclipse doesn't support these options and commands because they will obsolete in LTTng Tools v2.2.0 and because the procedure for session creation offers already all relevant advanced parameters.
+
+= How to use LTTng to diagnose problems =
+
+LTTng is a tracer, it will give an enormous amount of information about the system it is running on. This means it can solve many types of problems.
+
+The following are examples of problems that can be solved with a tracer.
+
+== Random stutters ==
+
+Bob is running a computer program and it stutters periodically every 2 minutes. The CPU load is relatively low and Bob isn't running low on RAM.
+
+He decides to trace his complete system for 10 minutes. He opens the LTTng view in eclipse. From the control, he creates a session and enables all kernel tracepoints.
+
+He now has a 10 GB trace file. He imports the trace to his viewer and loads it up.
+
+A cursory look at the histogram bar on the bottom show relatively even event distribution, there are no interesting spikes, so he will have to dig deeper to find the issue. If he had seen a spike every 2 minutes, there would be strong chances this would be the first thing to investigate as it would imply a lot of kernel activity at the same period as his glitch, this would have been a path to investigate.
+
+As Bob suspects that he may be having some hardware raising IRQs or some other hardware based issue and adding delays. He looks at the ressource view and doesn't see anything abnormal.
+
+Bob did note an exact second one glitch occured: 11:58:03. He zooms into the time range or 11:58:02-11:58:04 using the histogram.He is happy to see the time is human readable local wall clock time and no longer in "nanseconds since the last reboot". <br>In the resource view, once again, he sees many soft irqs being raised at the same time, around the time his gui would freeze. He changes views and looks at the control flow view at that time and sees a process spending a lot of time in the kernel: FooMonitor- his temperature monitoring software.
+
+At this point he closes FooMonitor and notices the bug dissapeared. He could call it a day but he wants to see what was causing the system to freeze. He cannot justify closing a piece of software without understanding the issue. It may be a conflict that HIS software is causing after all.
+
+The system freezes around the time this program is running. He clicks on the process in the control flow view and looks at the corresponding events in the detailed events view. He sees: open - read - close repeated hundreds of times on the same file. The file being read was /dev/HWmonitor. He sends a report to the FooMonitor team and warns his team that FooMonitor was glitching their performance.
+
+The FooMonitor team finds that they were calling a system bus call that would halt a cpu while reading the temperature so that the core would not induce an 0.1 degree error in the reading, by disabling this feature, they improve their software and stop the glitches from occurring on their custommer's machine. They also optimize their code to open the file read and clone it once.
+
+By using system wide kernel tracing, even without deep kernel knowledge Bob was able to isolate a bug in a rogue piece of software in his system.
+
+== Slow I/O ==
+
+Alice is running her server. She noticed that one of her nodes was slowing down, and wasn't sure why, upon reading the trace she noticed that her time between a block request and complete was around 10ms.
+
+This is abnormal, normally her server handles IOs in under 100us, since they are quite local.
+
+She walks up to the server and hears the hard drive thrashing, This prompts her to look up in the events view the sectors being read in the block complete requests. There are her requests interleaved with other ones at the opposite side of the hard drive.
+
+She sees the tracer writing but there is another process that is writing to the server disk non stop. She looks in the control flow view and sees that there's a program from another fellow engineer, "Wally" that is writing in his home in a loop "All work and no play makes Jack a dull boy.".
+
+Alice kills the program, and immediately the server speeds up. She then goes to discuss this with Wally and implements strict hard disk quotas on the server.
+
+= References =
+
+* [http://www.eclipse.org/linuxtools/projectPages/lttng/ Linux Tools - LTTng integration]
+* [http://www.lttng.org/ LTTng project]
+* [http://lttng.org/files/doc/man-pages/man1/lttng.1.html LTTng Tracer Control Command Line Tool User Manual]
+* [http://lttng.org/files/doc/man-pages/man8/lttng-relayd.8.html LTTng relayd User Manual]
+* [http://wiki.eclipse.org/Linux_Tools_Project/TMF/User_Guide TMF User Guide]
+
+= Updating This Document =
+
+This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide]
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass User Guide
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin>
+<!-- This part should be in a documentation plugin -->
+<!-- Configure the help contribution for this plugin -->
+ <extension point="org.eclipse.help.toc">
+ <toc
+ file="doc/User-Guide-toc.xml"
+ primary="true" />
+ </extension>
+</plugin>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2011, Red Hat, Inc.
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <artifactId>org.eclipse.tracecompass.doc</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.eclipse.tracecompass.doc.user</artifactId>
+ <version>0.1.0-SNAPSHOT</version>
+ <packaging>eclipse-plugin</packaging>
+
+ <name>Trace Compass User Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-documentation</id>
+ <phase>generate-sources</phase>
+ <configuration>
+ <echo>Generating Help Files</echo>
+ <target>
+ <property name="compile_classpath" refid="maven.compile.classpath" />
+ <ant target="build" inheritRefs="true" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>clean-documentation</id>
+ <phase>clean</phase>
+ <configuration>
+ <echo>Cleaning up generated Help Files</echo>
+ <target>
+ <ant target="clean" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-launcher</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-nodeps</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
+
+ <groupId>org.eclipse.tracecompass</groupId>
+</project>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>All Classes</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<h1 class="bar">All Classes</h1>\r
+<div class="indexContainer">\r
+<ul>\r
+<li><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp" target="classFrame">TmfTimestampFormat</a></li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>All Classes</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<h1 class="bar">All Classes</h1>\r
+<div class="indexContainer">\r
+<ul>\r
+<li><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>Constant Field Values</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<script type="text/javascript"><!--\r
+ if (location.href.indexOf('is-external=true') == -1) {\r
+ parent.document.title="Constant Field Values";\r
+ }\r
+//-->\r
+</script>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<div class="header">\r
+<h1 title="Constant Field Values" class="title">Constant Field Values</h1>\r
+<h2 title="Contents">Contents</h2>\r
+<ul>\r
+<li><a href="#org.eclipse">org.eclipse.*</a></li>\r
+</ul>\r
+</div>\r
+<div class="constantValuesContainer"><a name="org.eclipse">\r
+<!-- -->\r
+</a>\r
+<h2 title="org.eclipse">org.eclipse.*</h2>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<table border="0" cellpadding="3" cellspacing="0" summary="Constant Field Values table, listing constant fields, and values">\r
+<caption><span>org.eclipse.linuxtools.tmf.core.timestamp.<a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></span><span class="tabEnd"> </span></caption>\r
+<tr>\r
+<th class="colFirst" scope="col">Modifier and Type</th>\r
+<th scope="col">Constant Field</th>\r
+<th class="colLast" scope="col">Value</th>\r
+</tr>\r
+<tbody>\r
+<tr class="altColor">\r
+<td class="colFirst"><a name="org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_INTERVAL_PATTERN">\r
+<!-- -->\r
+</a><code>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
+<td><code><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_INTERVAL_PATTERN">DEFAULT_INTERVAL_PATTERN</a></code></td>\r
+<td class="colLast"><code>"TTT.SSS SSS SSS"</code></td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><a name="org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_TIME_PATTERN">\r
+<!-- -->\r
+</a><code>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
+<td><code><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_TIME_PATTERN">DEFAULT_TIME_PATTERN</a></code></td>\r
+<td class="colLast"><code>"HH:mm:ss.SSS SSS SSS"</code></td>\r
+</tr>\r
+</tbody>\r
+</table>\r
+</li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>Deprecated List</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<script type="text/javascript"><!--\r
+ if (location.href.indexOf('is-external=true') == -1) {\r
+ parent.document.title="Deprecated List";\r
+ }\r
+//-->\r
+</script>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<div class="header">\r
+<h1 title="Deprecated API" class="title">Deprecated API</h1>\r
+<h2 title="Contents">Contents</h2>\r
+<ul>\r
+<li><a href="#method">Deprecated Methods</a></li>\r
+</ul>\r
+</div>\r
+<div class="contentContainer"><a name="method">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<table border="0" cellpadding="3" cellspacing="0" summary="Deprecated Methods table, listing deprecated methods, and an explanation">\r
+<caption><span>Deprecated Methods</span><span class="tabEnd"> </span></caption>\r
+<tr>\r
+<th class="colOne" scope="col">Method and Description</th>\r
+</tr>\r
+<tbody>\r
+<tr class="altColor">\r
+<td class="colOne"><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultIntervalFormat(java.lang.String)">org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.setDefaultIntervalFormat(String)</a>\r
+<div class="block"><i>The default interval format pattern depends on the
+ preferences, see <code>TmfTimePreferences</code>. To change the
+ default time pattern, modify the preferences and call
+ <a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
+</td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colOne"><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultTimeFormat(java.lang.String)">org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.setDefaultTimeFormat(String)</a>\r
+<div class="block"><i>The default time pattern depends on the preferences, see
+ <code>TmfTimePreferences</code>. To change the default time
+ pattern, modify the preferences and call <a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
+</td>\r
+</tr>\r
+</tbody>\r
+</table>\r
+</li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>API Help</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<script type="text/javascript"><!--\r
+ if (location.href.indexOf('is-external=true') == -1) {\r
+ parent.document.title="API Help";\r
+ }\r
+//-->\r
+</script>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<div class="header">\r
+<h1 class="title">How This API Document Is Organized</h1>\r
+<div class="subTitle">This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.</div>\r
+</div>\r
+<div class="contentContainer">\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h2>Package</h2>\r
+<p>Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:</p>\r
+<ul>\r
+<li>Interfaces (italic)</li>\r
+<li>Classes</li>\r
+<li>Enums</li>\r
+<li>Exceptions</li>\r
+<li>Errors</li>\r
+<li>Annotation Types</li>\r
+</ul>\r
+</li>\r
+<li class="blockList">\r
+<h2>Class/Interface</h2>\r
+<p>Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:</p>\r
+<ul>\r
+<li>Class inheritance diagram</li>\r
+<li>Direct Subclasses</li>\r
+<li>All Known Subinterfaces</li>\r
+<li>All Known Implementing Classes</li>\r
+<li>Class/interface declaration</li>\r
+<li>Class/interface description</li>\r
+</ul>\r
+<ul>\r
+<li>Nested Class Summary</li>\r
+<li>Field Summary</li>\r
+<li>Constructor Summary</li>\r
+<li>Method Summary</li>\r
+</ul>\r
+<ul>\r
+<li>Field Detail</li>\r
+<li>Constructor Detail</li>\r
+<li>Method Detail</li>\r
+</ul>\r
+<p>Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.</p>\r
+</li>\r
+<li class="blockList">\r
+<h2>Annotation Type</h2>\r
+<p>Each annotation type has its own separate page with the following sections:</p>\r
+<ul>\r
+<li>Annotation Type declaration</li>\r
+<li>Annotation Type description</li>\r
+<li>Required Element Summary</li>\r
+<li>Optional Element Summary</li>\r
+<li>Element Detail</li>\r
+</ul>\r
+</li>\r
+<li class="blockList">\r
+<h2>Enum</h2>\r
+<p>Each enum has its own separate page with the following sections:</p>\r
+<ul>\r
+<li>Enum declaration</li>\r
+<li>Enum description</li>\r
+<li>Enum Constant Summary</li>\r
+<li>Enum Constant Detail</li>\r
+</ul>\r
+</li>\r
+<li class="blockList">\r
+<h2>Deprecated API</h2>\r
+<p>The <a href="deprecated-list.html">Deprecated API</a> page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.</p>\r
+</li>\r
+<li class="blockList">\r
+<h2>Prev/Next</h2>\r
+<p>These links take you to the next or previous class, interface, package, or related page.</p>\r
+</li>\r
+<li class="blockList">\r
+<h2>Frames/No Frames</h2>\r
+<p>These links show and hide the HTML frames. All pages are available with or without frames.</p>\r
+</li>\r
+<li class="blockList">\r
+<h2>All Classes</h2>\r
+<p>The <a href="allclasses-noframe.html">All Classes</a> link shows all classes and interfaces except non-static nested types.</p>\r
+</li>\r
+<li class="blockList">\r
+<h2>Serialized Form</h2>\r
+<p>Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.</p>\r
+</li>\r
+<li class="blockList">\r
+<h2>Constant Field Values</h2>\r
+<p>The <a href="constant-values.html">Constant Field Values</a> page lists the static final fields and their values.</p>\r
+</li>\r
+</ul>\r
+<em>This help file applies to API documentation generated using the standard doclet.</em></div>\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>Generated Documentation (Untitled)</title>\r
+<script type="text/javascript">\r
+ targetPage = "" + window.location.search;\r
+ if (targetPage != "" && targetPage != "undefined")\r
+ targetPage = targetPage.substring(1);\r
+ if (targetPage.indexOf(":") != -1 || (targetPage != "" && !validURL(targetPage)))\r
+ targetPage = "undefined";\r
+ function validURL(url) {\r
+ var pos = url.indexOf(".html");\r
+ if (pos == -1 || pos != url.length - 5)\r
+ return false;\r
+ var allowNumber = false;\r
+ var allowSep = false;\r
+ var seenDot = false;\r
+ for (var i = 0; i < url.length - 5; i++) {\r
+ var ch = url.charAt(i);\r
+ if ('a' <= ch && ch <= 'z' ||\r
+ 'A' <= ch && ch <= 'Z' ||\r
+ ch == '$' ||\r
+ ch == '_') {\r
+ allowNumber = true;\r
+ allowSep = true;\r
+ } else if ('0' <= ch && ch <= '9'\r
+ || ch == '-') {\r
+ if (!allowNumber)\r
+ return false;\r
+ } else if (ch == '/' || ch == '.') {\r
+ if (!allowSep)\r
+ return false;\r
+ allowNumber = false;\r
+ allowSep = false;\r
+ if (ch == '.')\r
+ seenDot = true;\r
+ if (ch == '/' && seenDot)\r
+ return false;\r
+ } else {\r
+ return false;\r
+ }\r
+ }\r
+ return true;\r
+ }\r
+ function loadFrames() {\r
+ if (targetPage != "" && targetPage != "undefined")\r
+ top.classFrame.location = top.targetPage;\r
+ }\r
+</script>\r
+</head>\r
+<frameset cols="20%,80%" title="Documentation frame" onload="top.loadFrames()">\r
+<frame src="allclasses-frame.html" name="packageFrame" title="All classes and interfaces (except non-static nested types)">\r
+<frame src="org/eclipse/linuxtools/tmf/core/timestamp/package-summary.html" name="classFrame" title="Package, class and interface descriptions" scrolling="yes">\r
+<noframes>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<h2>Frame Alert</h2>\r
+<p>This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client. Link to <a href="org/eclipse/linuxtools/tmf/core/timestamp/package-summary.html">Non-frame version</a>.</p>\r
+</noframes>\r
+</frameset>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>TmfTimestampFormat</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<script type="text/javascript"><!--\r
+ if (location.href.indexOf('is-external=true') == -1) {\r
+ parent.document.title="TmfTimestampFormat";\r
+ }\r
+//-->\r
+</script>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<!-- ======== START OF CLASS DATA ======== -->\r
+<div class="header">\r
+<div class="subTitle">org.eclipse.linuxtools.tmf.core.timestamp</div>\r
+<h2 title="Class TmfTimestampFormat" class="title">Class TmfTimestampFormat</h2>\r
+</div>\r
+<div class="contentContainer">\r
+<ul class="inheritance">\r
+<li><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">java.lang.Object</a></li>\r
+<li>\r
+<ul class="inheritance">\r
+<li><a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true" title="class or interface in java.text">java.text.Format</a></li>\r
+<li>\r
+<ul class="inheritance">\r
+<li><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">java.text.DateFormat</a></li>\r
+<li>\r
+<ul class="inheritance">\r
+<li><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">java.text.SimpleDateFormat</a></li>\r
+<li>\r
+<ul class="inheritance">\r
+<li>org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+<div class="description">\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<dl>\r
+<dt>All Implemented Interfaces:</dt>\r
+<dd><a href="http://download.oracle.com/javase/7/docs/api/java/io/Serializable.html?is-external=true" title="class or interface in java.io">Serializable</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Cloneable.html?is-external=true" title="class or interface in java.lang">Cloneable</a></dd>\r
+</dl>\r
+<hr>\r
+<br>\r
+<pre>public class <span class="strong">TmfTimestampFormat</span>\r
+extends <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></pre>\r
+<div class="block">A formatting and parsing facility that can handle timestamps that span the
+ epoch with a precision down to the nanosecond. It can be understood as an
+ extension of SimpleDateFormat that supports seconds since the epoch (Jan 1,
+ 1970, 00:00:00 GMT), additional sub-second patterns and optional delimiters.
+ <p>
+ The timestamp representation is broken down into a number of optional
+ components that can be assembled into a fairly simple way.
+
+ <h4>Date and Time Patterns</h4>
+ All date and time pattern letters defined in <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text"><code>SimpleDateFormat</code></a> are
+ supported with the following exceptions:
+ <blockquote>
+ <table border=0 cellspacing=3 cellpadding=0 >
+ <tr bgcolor="#ccccff">
+ <th align=left>Format
+ <th align=left>Description
+ <th align=left>Value Range
+ <th align=left>Example
+ <tr bgcolor="#eeeeff">
+ <td><code>T</code>
+ <td>The seconds since the epoch
+ <td><code>0-9223372036</code>
+ <td><code>1332170682</code>
+ <tr>
+ <td><code>S</code>
+ <td>Millisecond
+ <td><code>N/A</code>
+ <td><code>Not supported</code>
+ <tr bgcolor="#eeeeff">
+ <td><code>W</code>
+ <td>Week in month
+ <td><code>N/A</code>
+ <td><code>Not supported</code>
+ </table>
+ </blockquote>
+ <p>
+ <strong>Note:</strong> When parsing, if "T" is used, no other Date and Time
+ pattern letter will be interpreted and the entire pre-delimiter input string
+ will be parsed as a number. Also, "T" should be used for time intervals.
+ <p>
+ <strong>Note:</strong> The decimal separator between the Date and Time
+ pattern and the Sub-Seconds pattern is mandatory (if there is a fractional
+ part) and must be one of the sub-second delimiters. Date and Time pattern
+ letters are not interpreted after the decimal separator.
+ <p>
+ <h4>Sub-Seconds Patterns</h4>
+ <blockquote>
+ <table border=0 cellspacing=3 cellpadding=0 >
+ <tr bgcolor="#ccccff">
+ <th align=left>Format
+ <th align=left>Description
+ <th align=left>Value Range
+ <th align=left>Example
+ <tr>
+ <td><code>S</code>
+ <td>Fraction of second
+ <td><code>0-999999999</code>
+ <td><code>123456789</code>
+ <tr bgcolor="#eeeeff">
+ <td><code>C</code>
+ <td>Microseconds in ms
+ <td><code>0-999</code>
+ <td><code>456</code>
+ <tr>
+ <td><code>N</code>
+ <td>Nanoseconds in µs
+ <td><code>0-999</code>
+ <td><code>789</code>
+ </table>
+ </blockquote>
+ <strong>Note:</strong> The fraction of second pattern can be split, in which
+ case parsing and formatting continues at the next digit. Digits beyond the
+ total number of pattern letters are ignored when parsing and truncated when
+ formatting.
+ <p>
+ <strong>Note:</strong> When parsing, "S", "C" and "N" are interchangeable
+ and are all handled as fraction of second ("S"). The use of "C" and "N" is
+ discouraged but is supported for backward compatibility.
+ <p>
+
+ The recognized sub-second delimiters are:
+ <ul>
+ <li>Space ("<code> </code>")
+ <li>Period ("<code>.</code>")
+ <li>Comma ("<code>,</code>")
+ <li>Dash ("<code>-</code>")
+ <li>Underline ("<code>_</code>")
+ <li>Colon ("<code>:</code>")
+ <li>Semicolon ("<code>;</code>")
+ <li>Slash ("<code>/</code>")
+ <li>Single-quote ("<code>''</code>")
+ <li>Double-quote ("<code>"</code>")
+ </ul>
+ <p>
+ <strong>Note:</strong> When parsing, sub-second delimiters are optional if
+ unquoted. However, an extra delimiter or any other unexpected character in
+ the input string ends the parsing of digits. All other quoted or unquoted
+ characters in the sub-second pattern are matched against the input string.
+
+ <h4>Examples</h4>
+ The following examples show how timestamp patterns are interpreted in
+ the U.S. locale. The given timestamp is 1332170682539677389L, the number
+ of nanoseconds since 1970/01/01.
+
+ <blockquote>
+ <table border=0 cellspacing=3 cellpadding=0>
+ <tr bgcolor="#ccccff">
+ <th align=left>Date and Time Pattern
+ <th align=left>Result
+ <tr>
+ <td><code>"yyyy-MM-dd HH:mm:ss.SSS.SSS.SSS"</code>
+ <td><code>2012-03-19 11:24:42.539.677.389</code>
+ <tr bgcolor="#eeeeff">
+ <td><code>"yyyy-MM-dd HH:mm:ss.SSS.SSS"</code>
+ <td><code>2012-03-19 11:24:42.539.677</code>
+ <tr>
+ <td><code>"yyyy-D HH:mm:ss.SSS.SSS"</code>
+ <td><code>2012-79 11:24:42.539.677</code>
+ <tr bgcolor="#eeeeff">
+ <td><code>"ss,SSSS"</code>
+ <td><code>42,5397</code>
+ <tr>
+ <td><code>"T.SSS SSS SSS"</code>
+ <td><code>1332170682.539 677 389</code>
+ <tr bgcolor="#eeeeff">
+ <td><code>"T"</code>
+ <td><code>1332170682</code>
+ </table>
+ </blockquote>
+ <p></div>\r
+<dl><dt><span class="strong">Since:</span></dt>\r
+ <dd>2.0</dd>\r
+<dt><span class="strong">Version:</span></dt>\r
+ <dd>1.0</dd>\r
+<dt><span class="strong">Author:</span></dt>\r
+ <dd>Francois Chouinard</dd>\r
+<dt><span class="strong">See Also:</span></dt><dd><a href="../../../../../../serialized-form.html#org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat">Serialized Form</a></dd></dl>\r
+</li>\r
+</ul>\r
+</div>\r
+<div class="summary">\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<!-- ======== NESTED CLASS SUMMARY ======== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="nested_class_summary">\r
+<!-- -->\r
+</a>\r
+<h3>Nested Class Summary</h3>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="nested_classes_inherited_from_class_java.text.DateFormat">\r
+<!-- -->\r
+</a>\r
+<h3>Nested classes/interfaces inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">DateFormat</a></h3>\r
+<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.Field.html?is-external=true" title="class or interface in java.text">DateFormat.Field</a></code></li>\r
+</ul>\r
+</li>\r
+</ul>\r
+<!-- =========== FIELD SUMMARY =========== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="field_summary">\r
+<!-- -->\r
+</a>\r
+<h3>Field Summary</h3>\r
+<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Field Summary table, listing fields, and an explanation">\r
+<caption><span>Fields</span><span class="tabEnd"> </span></caption>\r
+<tr>\r
+<th class="colFirst" scope="col">Modifier and Type</th>\r
+<th class="colLast" scope="col">Field and Description</th>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colFirst"><code>static <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_INTERVAL_PATTERN">DEFAULT_INTERVAL_PATTERN</a></strong></code>\r
+<div class="block">The default interval pattern</div>\r
+</td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><code>static <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_TIME_PATTERN">DEFAULT_TIME_PATTERN</a></strong></code>\r
+<div class="block">The default timestamp pattern</div>\r
+</td>\r
+</tr>\r
+</table>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="fields_inherited_from_class_java.text.DateFormat">\r
+<!-- -->\r
+</a>\r
+<h3>Fields inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">DateFormat</a></h3>\r
+<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#AM_PM_FIELD" title="class or interface in java.text">AM_PM_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DATE_FIELD" title="class or interface in java.text">DATE_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DAY_OF_WEEK_FIELD" title="class or interface in java.text">DAY_OF_WEEK_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DAY_OF_WEEK_IN_MONTH_FIELD" title="class or interface in java.text">DAY_OF_WEEK_IN_MONTH_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DAY_OF_YEAR_FIELD" title="class or interface in java.text">DAY_OF_YEAR_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DEFAULT" title="class or interface in java.text">DEFAULT</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#ERA_FIELD" title="class or interface in java.text">ERA_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#FULL" title="class or interface in java.text">FULL</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR_OF_DAY0_FIELD" title="class or interface in java.text">HOUR_OF_DAY0_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR_OF_DAY1_FIELD" title="class or interface in java.text">HOUR_OF_DAY1_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR0_FIELD" title="class or interface in java.text">HOUR0_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR1_FIELD" title="class or interface in java.text">HOUR1_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#LONG" title="class or interface in java.text">LONG</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MEDIUM" title="class or interface in java.text">MEDIUM</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MILLISECOND_FIELD" title="class or interface in java.text">MILLISECOND_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MINUTE_FIELD" title="class or interface in java.text">MINUTE_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MONTH_FIELD" title="class or interface in java.text">MONTH_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#SECOND_FIELD" title="class or interface in java.text">SECOND_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#SHORT" title="class or interface in java.text">SHORT</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#TIMEZONE_FIELD" title="class or interface in java.text">TIMEZONE_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#WEEK_OF_MONTH_FIELD" title="class or interface in java.text">WEEK_OF_MONTH_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#WEEK_OF_YEAR_FIELD" title="class or interface in java.text">WEEK_OF_YEAR_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#YEAR_FIELD" title="class or interface in java.text">YEAR_FIELD</a></code></li>\r
+</ul>\r
+</li>\r
+</ul>\r
+<!-- ======== CONSTRUCTOR SUMMARY ======== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="constructor_summary">\r
+<!-- -->\r
+</a>\r
+<h3>Constructor Summary</h3>\r
+<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Constructor Summary table, listing constructors, and an explanation">\r
+<caption><span>Constructors</span><span class="tabEnd"> </span></caption>\r
+<tr>\r
+<th class="colOne" scope="col">Constructor and Description</th>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat()">TmfTimestampFormat</a></strong>()</code>\r
+<div class="block">The default constructor (uses the default pattern)</div>\r
+</td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat(java.lang.String)">TmfTimestampFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code>\r
+<div class="block">The normal constructor</div>\r
+</td>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat(java.lang.String, java.util.TimeZone)">TmfTimestampFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern,\r
+ <a href="http://download.oracle.com/javase/7/docs/api/java/util/TimeZone.html?is-external=true" title="class or interface in java.util">TimeZone</a> timeZone)</code>\r
+<div class="block">The full constructor</div>\r
+</td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat(org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat)">TmfTimestampFormat</a></strong>(<a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> other)</code>\r
+<div class="block">The copy constructor</div>\r
+</td>\r
+</tr>\r
+</table>\r
+</li>\r
+</ul>\r
+<!-- ========== METHOD SUMMARY =========== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="method_summary">\r
+<!-- -->\r
+</a>\r
+<h3>Method Summary</h3>\r
+<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">\r
+<caption><span>Methods</span><span class="tabEnd"> </span></caption>\r
+<tr>\r
+<th class="colFirst" scope="col">Modifier and Type</th>\r
+<th class="colLast" scope="col">Method and Description</th>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colFirst"><code>void</code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#applyPattern(java.lang.String)">applyPattern</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code> </td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><code><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#format(long)">format</a></strong>(long value)</code>\r
+<div class="block">Format the timestamp according to its pattern.</div>\r
+</td>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colFirst"><code>static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#getDefaulIntervalFormat()">getDefaulIntervalFormat</a></strong>()</code> </td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><code>static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#getDefaulTimeFormat()">getDefaulTimeFormat</a></strong>()</code> </td>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colFirst"><code>long</code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#parseValue(java.lang.String)">parseValue</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source)</code>\r
+<div class="block">Parse a string according to the format pattern</div>\r
+</td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><code>long</code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#parseValue(java.lang.String, long)">parseValue</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source,\r
+ long ref)</code>\r
+<div class="block">Parse a string according to the format pattern</div>\r
+</td>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colFirst"><code>static void</code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultIntervalFormat(java.lang.String)">setDefaultIntervalFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code>\r
+<div class="block"><strong>Deprecated.</strong> \r
+<div class="block"><i>The default interval format pattern depends on the
+ preferences, see <code>TmfTimePreferences</code>. To change the
+ default time pattern, modify the preferences and call
+ <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
+</div>\r
+</td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><code>static void</code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultTimeFormat(java.lang.String)">setDefaultTimeFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code>\r
+<div class="block"><strong>Deprecated.</strong> \r
+<div class="block"><i>The default time pattern depends on the preferences, see
+ <code>TmfTimePreferences</code>. To change the default time
+ pattern, modify the preferences and call <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
+</div>\r
+</td>\r
+</tr>\r
+<tr class="altColor">\r
+<td class="colFirst"><code><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#toPattern()">toPattern</a></strong>()</code> </td>\r
+</tr>\r
+<tr class="rowColor">\r
+<td class="colFirst"><code>static void</code></td>\r
+<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()">updateDefaultFormats</a></strong>()</code> </td>\r
+</tr>\r
+</table>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="methods_inherited_from_class_java.text.SimpleDateFormat">\r
+<!-- -->\r
+</a>\r
+<h3>Methods inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></h3>\r
+<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#applyLocalizedPattern(java.lang.String)" title="class or interface in java.text">applyLocalizedPattern</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#clone()" title="class or interface in java.text">clone</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.text">equals</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#format(java.util.Date, java.lang.StringBuffer, java.text.FieldPosition)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#formatToCharacterIterator(java.lang.Object)" title="class or interface in java.text">formatToCharacterIterator</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#get2DigitYearStart()" title="class or interface in java.text">get2DigitYearStart</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#getDateFormatSymbols()" title="class or interface in java.text">getDateFormatSymbols</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#hashCode()" title="class or interface in java.text">hashCode</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#parse(java.lang.String, java.text.ParsePosition)" title="class or interface in java.text">parse</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#set2DigitYearStart(java.util.Date)" title="class or interface in java.text">set2DigitYearStart</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#setDateFormatSymbols(java.text.DateFormatSymbols)" title="class or interface in java.text">setDateFormatSymbols</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#toLocalizedPattern()" title="class or interface in java.text">toLocalizedPattern</a></code></li>\r
+</ul>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="methods_inherited_from_class_java.text.DateFormat">\r
+<!-- -->\r
+</a>\r
+<h3>Methods inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">DateFormat</a></h3>\r
+<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#format(java.util.Date)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getAvailableLocales()" title="class or interface in java.text">getAvailableLocales</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getCalendar()" title="class or interface in java.text">getCalendar</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateInstance()" title="class or interface in java.text">getDateInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateInstance(int)" title="class or interface in java.text">getDateInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateInstance(int, java.util.Locale)" title="class or interface in java.text">getDateInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateTimeInstance()" title="class or interface in java.text">getDateTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateTimeInstance(int, int)" title="class or interface in java.text">getDateTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateTimeInstance(int, int, java.util.Locale)" title="class or interface in java.text">getDateTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getInstance()" title="class or interface in java.text">getInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getNumberFormat()" title="class or interface in java.text">getNumberFormat</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeInstance()" title="class or interface in java.text">getTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeInstance(int)" title="class or interface in java.text">getTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeInstance(int, java.util.Locale)" title="class or interface in java.text">getTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeZone()" title="class or interface in java.text">getTimeZone</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#isLenient()" title="class or interface in java.text">isLenient</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#parse(java.lang.String)" title="class or interface in java.text">parse</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#parseObject(java.lang.String, java.text.ParsePosition)" title="class or interface in java.text">parseObject</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setCalendar(java.util.Calendar)" title="class or interface in java.text">setCalendar</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setLenient(boolean)" title="class or interface in java.text">setLenient</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setNumberFormat(java.text.NumberFormat)" title="class or interface in java.text">setNumberFormat</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setTimeZone(java.util.TimeZone)" title="class or interface in java.text">setTimeZone</a></code></li>\r
+</ul>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="methods_inherited_from_class_java.text.Format">\r
+<!-- -->\r
+</a>\r
+<h3>Methods inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true" title="class or interface in java.text">Format</a></h3>\r
+<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true#format(java.lang.Object)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true#parseObject(java.lang.String)" title="class or interface in java.text">parseObject</a></code></li>\r
+</ul>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="methods_inherited_from_class_java.lang.Object">\r
+<!-- -->\r
+</a>\r
+<h3>Methods inherited from class java.lang.<a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a></h3>\r
+<code><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang">getClass</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang">notify</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang">notifyAll</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang">toString</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang">wait</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang">wait</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long, int)" title="class or interface in java.lang">wait</a></code></li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</div>\r
+<div class="details">\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<!-- ============ FIELD DETAIL =========== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="field_detail">\r
+<!-- -->\r
+</a>\r
+<h3>Field Detail</h3>\r
+<a name="DEFAULT_TIME_PATTERN">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>DEFAULT_TIME_PATTERN</h4>\r
+<pre>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> DEFAULT_TIME_PATTERN</pre>\r
+<div class="block">The default timestamp pattern</div>\r
+<dl><dt><span class="strong">See Also:</span></dt><dd><a href="../../../../../../constant-values.html#org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_TIME_PATTERN">Constant Field Values</a></dd></dl>\r
+</li>\r
+</ul>\r
+<a name="DEFAULT_INTERVAL_PATTERN">\r
+<!-- -->\r
+</a>\r
+<ul class="blockListLast">\r
+<li class="blockList">\r
+<h4>DEFAULT_INTERVAL_PATTERN</h4>\r
+<pre>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> DEFAULT_INTERVAL_PATTERN</pre>\r
+<div class="block">The default interval pattern</div>\r
+<dl><dt><span class="strong">See Also:</span></dt><dd><a href="../../../../../../constant-values.html#org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_INTERVAL_PATTERN">Constant Field Values</a></dd></dl>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+<!-- ========= CONSTRUCTOR DETAIL ======== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="constructor_detail">\r
+<!-- -->\r
+</a>\r
+<h3>Constructor Detail</h3>\r
+<a name="TmfTimestampFormat()">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>TmfTimestampFormat</h4>\r
+<pre>public TmfTimestampFormat()</pre>\r
+<div class="block">The default constructor (uses the default pattern)</div>\r
+</li>\r
+</ul>\r
+<a name="TmfTimestampFormat(java.lang.String)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>TmfTimestampFormat</h4>\r
+<pre>public TmfTimestampFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
+<div class="block">The normal constructor</div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the format pattern</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="TmfTimestampFormat(java.lang.String, java.util.TimeZone)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>TmfTimestampFormat</h4>\r
+<pre>public TmfTimestampFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern,\r
+ <a href="http://download.oracle.com/javase/7/docs/api/java/util/TimeZone.html?is-external=true" title="class or interface in java.util">TimeZone</a> timeZone)</pre>\r
+<div class="block">The full constructor</div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the format pattern</dd><dd><code>timeZone</code> - the time zone</dd><dt><span class="strong">Since:</span></dt>\r
+ <dd>2.1</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="TmfTimestampFormat(org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockListLast">\r
+<li class="blockList">\r
+<h4>TmfTimestampFormat</h4>\r
+<pre>public TmfTimestampFormat(<a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> other)</pre>\r
+<div class="block">The copy constructor</div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>other</code> - the other format pattern</dd></dl>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+<!-- ============ METHOD DETAIL ========== -->\r
+<ul class="blockList">\r
+<li class="blockList"><a name="method_detail">\r
+<!-- -->\r
+</a>\r
+<h3>Method Detail</h3>\r
+<a name="updateDefaultFormats()">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>updateDefaultFormats</h4>\r
+<pre>public static void updateDefaultFormats()</pre>\r
+<dl><dt><span class="strong">Since:</span></dt>\r
+ <dd>2.1</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="setDefaultTimeFormat(java.lang.String)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>setDefaultTimeFormat</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Deprecated.html?is-external=true" title="class or interface in java.lang">@Deprecated</a>\r
+public static void setDefaultTimeFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
+<div class="block"><span class="strong">Deprecated.</span> <i>The default time pattern depends on the preferences, see
+ <code>TmfTimePreferences</code>. To change the default time
+ pattern, modify the preferences and call <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the new default time pattern</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="getDefaulTimeFormat()">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>getDefaulTimeFormat</h4>\r
+<pre>public static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> getDefaulTimeFormat()</pre>\r
+<dl><dt><span class="strong">Returns:</span></dt><dd>the default time format pattern</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="setDefaultIntervalFormat(java.lang.String)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>setDefaultIntervalFormat</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Deprecated.html?is-external=true" title="class or interface in java.lang">@Deprecated</a>\r
+public static void setDefaultIntervalFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
+<div class="block"><span class="strong">Deprecated.</span> <i>The default interval format pattern depends on the
+ preferences, see <code>TmfTimePreferences</code>. To change the
+ default time pattern, modify the preferences and call
+ <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the new default interval pattern</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="getDefaulIntervalFormat()">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>getDefaulIntervalFormat</h4>\r
+<pre>public static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> getDefaulIntervalFormat()</pre>\r
+<dl><dt><span class="strong">Returns:</span></dt><dd>the default interval format pattern</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="applyPattern(java.lang.String)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>applyPattern</h4>\r
+<pre>public void applyPattern(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
+<dl>\r
+<dt><strong>Overrides:</strong></dt>\r
+<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#applyPattern(java.lang.String)" title="class or interface in java.text">applyPattern</a></code> in class <code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></code></dd>\r
+</dl>\r
+</li>\r
+</ul>\r
+<a name="toPattern()">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>toPattern</h4>\r
+<pre>public <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> toPattern()</pre>\r
+<dl>\r
+<dt><strong>Overrides:</strong></dt>\r
+<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#toPattern()" title="class or interface in java.text">toPattern</a></code> in class <code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></code></dd>\r
+</dl>\r
+</li>\r
+</ul>\r
+<a name="format(long)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>format</h4>\r
+<pre>public <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> format(long value)</pre>\r
+<div class="block">Format the timestamp according to its pattern.</div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>value</code> - the timestamp value to format (in ns)</dd>\r
+<dt><span class="strong">Returns:</span></dt><dd>the formatted timestamp</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="parseValue(java.lang.String, long)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>parseValue</h4>\r
+<pre>public long parseValue(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source,\r
+ long ref)\r
+ throws <a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></pre>\r
+<div class="block">Parse a string according to the format pattern</div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>source</code> - the source string</dd><dd><code>ref</code> - the reference (base) time (in ns)</dd>\r
+<dt><span class="strong">Returns:</span></dt><dd>the parsed value (in ns)</dd>\r
+<dt><span class="strong">Throws:</span></dt>\r
+<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></code> - if the string has an invalid format</dd></dl>\r
+</li>\r
+</ul>\r
+<a name="parseValue(java.lang.String)">\r
+<!-- -->\r
+</a>\r
+<ul class="blockListLast">\r
+<li class="blockList">\r
+<h4>parseValue</h4>\r
+<pre>public long parseValue(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source)\r
+ throws <a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></pre>\r
+<div class="block">Parse a string according to the format pattern</div>\r
+<dl><dt><span class="strong">Parameters:</span></dt><dd><code>source</code> - the source string</dd>\r
+<dt><span class="strong">Returns:</span></dt><dd>the parsed value (in ns)</dd>\r
+<dt><span class="strong">Throws:</span></dt>\r
+<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></code> - if the string has an invalid format</dd></dl>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</div>\r
+</div>\r
+<!-- ========= END OF CLASS DATA ========= -->\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>org.eclipse.linuxtools.tmf.core.timestamp</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<h1 class="bar"><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/package-summary.html" target="classFrame">org.eclipse.linuxtools.tmf.core.timestamp</a></h1>\r
+<div class="indexContainer">\r
+<h2 title="Classes">Classes</h2>\r
+<ul title="Classes">\r
+<li><a href="TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp" target="classFrame">TmfTimestampFormat</a></li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>org.eclipse.linuxtools.tmf.core.timestamp</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<script type="text/javascript"><!--\r
+ if (location.href.indexOf('is-external=true') == -1) {\r
+ parent.document.title="org.eclipse.linuxtools.tmf.core.timestamp";\r
+ }\r
+//-->\r
+</script>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<div class="header">\r
+<h1 title="Package" class="title">Package org.eclipse.linuxtools.tmf.core.timestamp</h1>\r
+</div>\r
+<div class="contentContainer">\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<table class="packageSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation">\r
+<caption><span>Class Summary</span><span class="tabEnd"> </span></caption>\r
+<tr>\r
+<th class="colFirst" scope="col">Class</th>\r
+<th class="colLast" scope="col">Description</th>\r
+</tr>\r
+<tbody>\r
+<tr class="altColor">\r
+<td class="colFirst"><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></td>\r
+<td class="colLast">\r
+<div class="block">A formatting and parsing facility that can handle timestamps that span the
+ epoch with a precision down to the nanosecond.</div>\r
+</td>\r
+</tr>\r
+</tbody>\r
+</table>\r
+</li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+org.eclipse.linuxtools.tmf.core.timestamp\r
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
+<!-- NewPage -->\r
+<html lang="en">\r
+<head>\r
+<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
+<title>Serialized Form</title>\r
+<meta name="date" content="2014-02-22">\r
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
+</head>\r
+<body>\r
+<script type="text/javascript"><!--\r
+ if (location.href.indexOf('is-external=true') == -1) {\r
+ parent.document.title="Serialized Form";\r
+ }\r
+//-->\r
+</script>\r
+<noscript>\r
+<div>JavaScript is disabled on your browser.</div>\r
+</noscript>\r
+<div class="header">\r
+<h1 title="Serialized Form" class="title">Serialized Form</h1>\r
+</div>\r
+<div class="serializedFormContainer">\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h2 title="Package">Package org.eclipse.linuxtools.tmf.core.timestamp</h2>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat">\r
+<!-- -->\r
+</a>\r
+<h3>Class <a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat</a> extends <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a> implements Serializable</h3>\r
+<dl class="nameValue">\r
+<dt>serialVersionUID:</dt>\r
+<dd>2835829763122454020L</dd>\r
+</dl>\r
+<ul class="blockList">\r
+<li class="blockList"><a name="serializedForm">\r
+<!-- -->\r
+</a>\r
+<h3>Serialized Fields</h3>\r
+<ul class="blockList">\r
+<li class="blockList">\r
+<h4>fPattern</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fPattern</pre>\r
+</li>\r
+<li class="blockList">\r
+<h4>fPatternDecimalSeparatorIndex</h4>\r
+<pre>int fPatternDecimalSeparatorIndex</pre>\r
+</li>\r
+<li class="blockList">\r
+<h4>fDecimalSeparator</h4>\r
+<pre>char fDecimalSeparator</pre>\r
+</li>\r
+<li class="blockList">\r
+<h4>fDateTimePattern</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fDateTimePattern</pre>\r
+</li>\r
+<li class="blockList">\r
+<h4>fSubSecPattern</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fSubSecPattern</pre>\r
+</li>\r
+<li class="blockList">\r
+<h4>fSupplPatterns</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/util/List.html?is-external=true" title="class or interface in java.util">List</a><<a href="http://download.oracle.com/javase/7/docs/api/java/util/List.html?is-external=true" title="class or interface in java.util">E</a>> fSupplPatterns</pre>\r
+</li>\r
+<li class="blockList">\r
+<h4>fSupplPatternLetters</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fSupplPatternLetters</pre>\r
+<div class="block">The supplementary pattern letters. Can be redefined by sub-classes
+ to either override existing letters or augment the letter set.
+ If so, the format() method must provide the (re-)implementation of the
+ pattern.</div>\r
+</li>\r
+<li class="blockList">\r
+<h4>fSubSecPatternChars</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fSubSecPatternChars</pre>\r
+<div class="block">The sub-second pattern letters.</div>\r
+<dl><dt><span class="strong">Since:</span></dt>\r
+ <dd>3.0</dd></dl>\r
+</li>\r
+<li class="blockList">\r
+<h4>fDelimiterChars</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fDelimiterChars</pre>\r
+<div class="block">The optional sub-second delimiter characters.</div>\r
+<dl><dt><span class="strong">Since:</span></dt>\r
+ <dd>3.0</dd></dl>\r
+</li>\r
+<li class="blockList">\r
+<h4>fOpenBracket</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fOpenBracket</pre>\r
+<div class="block">The open bracket symbol</div>\r
+</li>\r
+<li class="blockListLast">\r
+<h4>fCloseBracket</h4>\r
+<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fCloseBracket</pre>\r
+<div class="block">The closing bracket symbol</div>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</li>\r
+</ul>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+/* Javadoc style sheet */\r
+/*\r
+Overall document style\r
+*/\r
+body {\r
+ background-color:#ffffff;\r
+ color:#353833;\r
+ font-family:Arial, Helvetica, sans-serif;\r
+ font-size:76%;\r
+ margin:0;\r
+}\r
+a:link, a:visited {\r
+ text-decoration:none;\r
+ color:#4c6b87;\r
+}\r
+a:hover, a:focus {\r
+ text-decoration:none;\r
+ color:#bb7a2a;\r
+}\r
+a:active {\r
+ text-decoration:none;\r
+ color:#4c6b87;\r
+}\r
+a[name] {\r
+ color:#353833;\r
+}\r
+a[name]:hover {\r
+ text-decoration:none;\r
+ color:#353833;\r
+}\r
+pre {\r
+ font-size:1.3em;\r
+}\r
+h1 {\r
+ font-size:1.8em;\r
+}\r
+h2 {\r
+ font-size:1.5em;\r
+}\r
+h3 {\r
+ font-size:1.4em;\r
+}\r
+h4 {\r
+ font-size:1.3em;\r
+}\r
+h5 {\r
+ font-size:1.2em;\r
+}\r
+h6 {\r
+ font-size:1.1em;\r
+}\r
+ul {\r
+ list-style-type:disc;\r
+}\r
+code, tt {\r
+ font-size:1.2em;\r
+}\r
+dt code {\r
+ font-size:1.2em;\r
+}\r
+table tr td dt code {\r
+ font-size:1.2em;\r
+ vertical-align:top;\r
+}\r
+sup {\r
+ font-size:.6em;\r
+}\r
+/*\r
+Document title and Copyright styles\r
+*/\r
+.clear {\r
+ clear:both;\r
+ height:0px;\r
+ overflow:hidden;\r
+}\r
+.aboutLanguage {\r
+ float:right;\r
+ padding:0px 21px;\r
+ font-size:.8em;\r
+ z-index:200;\r
+ margin-top:-7px;\r
+}\r
+.legalCopy {\r
+ margin-left:.5em;\r
+}\r
+.bar a, .bar a:link, .bar a:visited, .bar a:active {\r
+ color:#FFFFFF;\r
+ text-decoration:none;\r
+}\r
+.bar a:hover, .bar a:focus {\r
+ color:#bb7a2a;\r
+}\r
+.tab {\r
+ background-color:#0066FF;\r
+ background-image:url(resources/titlebar.gif);\r
+ background-position:left top;\r
+ background-repeat:no-repeat;\r
+ color:#ffffff;\r
+ padding:8px;\r
+ width:5em;\r
+ font-weight:bold;\r
+}\r
+/*\r
+Navigation bar styles\r
+*/\r
+.bar {\r
+ background-image:url(resources/background.gif);\r
+ background-repeat:repeat-x;\r
+ color:#FFFFFF;\r
+ padding:.8em .5em .4em .8em;\r
+ height:auto;/*height:1.8em;*/\r
+ font-size:1em;\r
+ margin:0;\r
+}\r
+.topNav {\r
+ background-image:url(resources/background.gif);\r
+ background-repeat:repeat-x;\r
+ color:#FFFFFF;\r
+ float:left;\r
+ padding:0;\r
+ width:100%;\r
+ clear:right;\r
+ height:2.8em;\r
+ padding-top:10px;\r
+ overflow:hidden;\r
+}\r
+.bottomNav {\r
+ margin-top:10px;\r
+ background-image:url(resources/background.gif);\r
+ background-repeat:repeat-x;\r
+ color:#FFFFFF;\r
+ float:left;\r
+ padding:0;\r
+ width:100%;\r
+ clear:right;\r
+ height:2.8em;\r
+ padding-top:10px;\r
+ overflow:hidden;\r
+}\r
+.subNav {\r
+ background-color:#dee3e9;\r
+ border-bottom:1px solid #9eadc0;\r
+ float:left;\r
+ width:100%;\r
+ overflow:hidden;\r
+}\r
+.subNav div {\r
+ clear:left;\r
+ float:left;\r
+ padding:0 0 5px 6px;\r
+}\r
+ul.navList, ul.subNavList {\r
+ float:left;\r
+ margin:0 25px 0 0;\r
+ padding:0;\r
+}\r
+ul.navList li{\r
+ list-style:none;\r
+ float:left;\r
+ padding:3px 6px;\r
+}\r
+ul.subNavList li{\r
+ list-style:none;\r
+ float:left;\r
+ font-size:90%;\r
+}\r
+.topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited {\r
+ color:#FFFFFF;\r
+ text-decoration:none;\r
+}\r
+.topNav a:hover, .bottomNav a:hover {\r
+ text-decoration:none;\r
+ color:#bb7a2a;\r
+}\r
+.navBarCell1Rev {\r
+ background-image:url(resources/tab.gif);\r
+ background-color:#a88834;\r
+ color:#FFFFFF;\r
+ margin: auto 5px;\r
+ border:1px solid #c9aa44;\r
+}\r
+/*\r
+Page header and footer styles\r
+*/\r
+.header, .footer {\r
+ clear:both;\r
+ margin:0 20px;\r
+ padding:5px 0 0 0;\r
+}\r
+.indexHeader {\r
+ margin:10px;\r
+ position:relative;\r
+}\r
+.indexHeader h1 {\r
+ font-size:1.3em;\r
+}\r
+.title {\r
+ color:#2c4557;\r
+ margin:10px 0;\r
+}\r
+.subTitle {\r
+ margin:5px 0 0 0;\r
+}\r
+.header ul {\r
+ margin:0 0 25px 0;\r
+ padding:0;\r
+}\r
+.footer ul {\r
+ margin:20px 0 5px 0;\r
+}\r
+.header ul li, .footer ul li {\r
+ list-style:none;\r
+ font-size:1.2em;\r
+}\r
+/*\r
+Heading styles\r
+*/\r
+div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {\r
+ background-color:#dee3e9;\r
+ border-top:1px solid #9eadc0;\r
+ border-bottom:1px solid #9eadc0;\r
+ margin:0 0 6px -8px;\r
+ padding:2px 5px;\r
+}\r
+ul.blockList ul.blockList ul.blockList li.blockList h3 {\r
+ background-color:#dee3e9;\r
+ border-top:1px solid #9eadc0;\r
+ border-bottom:1px solid #9eadc0;\r
+ margin:0 0 6px -8px;\r
+ padding:2px 5px;\r
+}\r
+ul.blockList ul.blockList li.blockList h3 {\r
+ padding:0;\r
+ margin:15px 0;\r
+}\r
+ul.blockList li.blockList h2 {\r
+ padding:0px 0 20px 0;\r
+}\r
+/*\r
+Page layout container styles\r
+*/\r
+.contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer {\r
+ clear:both;\r
+ padding:10px 20px;\r
+ position:relative;\r
+}\r
+.indexContainer {\r
+ margin:10px;\r
+ position:relative;\r
+ font-size:1.0em;\r
+}\r
+.indexContainer h2 {\r
+ font-size:1.1em;\r
+ padding:0 0 3px 0;\r
+}\r
+.indexContainer ul {\r
+ margin:0;\r
+ padding:0;\r
+}\r
+.indexContainer ul li {\r
+ list-style:none;\r
+}\r
+.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {\r
+ font-size:1.1em;\r
+ font-weight:bold;\r
+ margin:10px 0 0 0;\r
+ color:#4E4E4E;\r
+}\r
+.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {\r
+ margin:10px 0 10px 20px;\r
+}\r
+.serializedFormContainer dl.nameValue dt {\r
+ margin-left:1px;\r
+ font-size:1.1em;\r
+ display:inline;\r
+ font-weight:bold;\r
+}\r
+.serializedFormContainer dl.nameValue dd {\r
+ margin:0 0 0 1px;\r
+ font-size:1.1em;\r
+ display:inline;\r
+}\r
+/*\r
+List styles\r
+*/\r
+ul.horizontal li {\r
+ display:inline;\r
+ font-size:0.9em;\r
+}\r
+ul.inheritance {\r
+ margin:0;\r
+ padding:0;\r
+}\r
+ul.inheritance li {\r
+ display:inline;\r
+ list-style:none;\r
+}\r
+ul.inheritance li ul.inheritance {\r
+ margin-left:15px;\r
+ padding-left:15px;\r
+ padding-top:1px;\r
+}\r
+ul.blockList, ul.blockListLast {\r
+ margin:10px 0 10px 0;\r
+ padding:0;\r
+}\r
+ul.blockList li.blockList, ul.blockListLast li.blockList {\r
+ list-style:none;\r
+ margin-bottom:25px;\r
+}\r
+ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList {\r
+ padding:0px 20px 5px 10px;\r
+ border:1px solid #9eadc0;\r
+ background-color:#f9f9f9;\r
+}\r
+ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList {\r
+ padding:0 0 5px 8px;\r
+ background-color:#ffffff;\r
+ border:1px solid #9eadc0;\r
+ border-top:none;\r
+}\r
+ul.blockList ul.blockList ul.blockList ul.blockList li.blockList {\r
+ margin-left:0;\r
+ padding-left:0;\r
+ padding-bottom:15px;\r
+ border:none;\r
+ border-bottom:1px solid #9eadc0;\r
+}\r
+ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast {\r
+ list-style:none;\r
+ border-bottom:none;\r
+ padding-bottom:0;\r
+}\r
+table tr td dl, table tr td dl dt, table tr td dl dd {\r
+ margin-top:0;\r
+ margin-bottom:1px;\r
+}\r
+/*\r
+Table styles\r
+*/\r
+.contentContainer table, .classUseContainer table, .constantValuesContainer table {\r
+ border-bottom:1px solid #9eadc0;\r
+ width:100%;\r
+}\r
+.contentContainer ul li table, .classUseContainer ul li table, .constantValuesContainer ul li table {\r
+ width:100%;\r
+}\r
+.contentContainer .description table, .contentContainer .details table {\r
+ border-bottom:none;\r
+}\r
+.contentContainer ul li table th.colOne, .contentContainer ul li table th.colFirst, .contentContainer ul li table th.colLast, .classUseContainer ul li table th, .constantValuesContainer ul li table th, .contentContainer ul li table td.colOne, .contentContainer ul li table td.colFirst, .contentContainer ul li table td.colLast, .classUseContainer ul li table td, .constantValuesContainer ul li table td{\r
+ vertical-align:top;\r
+ padding-right:20px;\r
+}\r
+.contentContainer ul li table th.colLast, .classUseContainer ul li table th.colLast,.constantValuesContainer ul li table th.colLast,\r
+.contentContainer ul li table td.colLast, .classUseContainer ul li table td.colLast,.constantValuesContainer ul li table td.colLast,\r
+.contentContainer ul li table th.colOne, .classUseContainer ul li table th.colOne,\r
+.contentContainer ul li table td.colOne, .classUseContainer ul li table td.colOne {\r
+ padding-right:3px;\r
+}\r
+.overviewSummary caption, .packageSummary caption, .contentContainer ul.blockList li.blockList caption, .summary caption, .classUseContainer caption, .constantValuesContainer caption {\r
+ position:relative;\r
+ text-align:left;\r
+ background-repeat:no-repeat;\r
+ color:#FFFFFF;\r
+ font-weight:bold;\r
+ clear:none;\r
+ overflow:hidden;\r
+ padding:0px;\r
+ margin:0px;\r
+}\r
+caption a:link, caption a:hover, caption a:active, caption a:visited {\r
+ color:#FFFFFF;\r
+}\r
+.overviewSummary caption span, .packageSummary caption span, .contentContainer ul.blockList li.blockList caption span, .summary caption span, .classUseContainer caption span, .constantValuesContainer caption span {\r
+ white-space:nowrap;\r
+ padding-top:8px;\r
+ padding-left:8px;\r
+ display:block;\r
+ float:left;\r
+ background-image:url(resources/titlebar.gif);\r
+ height:18px;\r
+}\r
+.overviewSummary .tabEnd, .packageSummary .tabEnd, .contentContainer ul.blockList li.blockList .tabEnd, .summary .tabEnd, .classUseContainer .tabEnd, .constantValuesContainer .tabEnd {\r
+ width:10px;\r
+ background-image:url(resources/titlebar_end.gif);\r
+ background-repeat:no-repeat;\r
+ background-position:top right;\r
+ position:relative;\r
+ float:left;\r
+}\r
+ul.blockList ul.blockList li.blockList table {\r
+ margin:0 0 12px 0px;\r
+ width:100%;\r
+}\r
+.tableSubHeadingColor {\r
+ background-color: #EEEEFF;\r
+}\r
+.altColor {\r
+ background-color:#eeeeef;\r
+}\r
+.rowColor {\r
+ background-color:#ffffff;\r
+}\r
+.overviewSummary td, .packageSummary td, .contentContainer ul.blockList li.blockList td, .summary td, .classUseContainer td, .constantValuesContainer td {\r
+ text-align:left;\r
+ padding:3px 3px 3px 7px;\r
+}\r
+th.colFirst, th.colLast, th.colOne, .constantValuesContainer th {\r
+ background:#dee3e9;\r
+ border-top:1px solid #9eadc0;\r
+ border-bottom:1px solid #9eadc0;\r
+ text-align:left;\r
+ padding:3px 3px 3px 7px;\r
+}\r
+td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover {\r
+ font-weight:bold;\r
+}\r
+td.colFirst, th.colFirst {\r
+ border-left:1px solid #9eadc0;\r
+ white-space:nowrap;\r
+}\r
+td.colLast, th.colLast {\r
+ border-right:1px solid #9eadc0;\r
+}\r
+td.colOne, th.colOne {\r
+ border-right:1px solid #9eadc0;\r
+ border-left:1px solid #9eadc0;\r
+}\r
+table.overviewSummary {\r
+ padding:0px;\r
+ margin-left:0px;\r
+}\r
+table.overviewSummary td.colFirst, table.overviewSummary th.colFirst,\r
+table.overviewSummary td.colOne, table.overviewSummary th.colOne {\r
+ width:25%;\r
+ vertical-align:middle;\r
+}\r
+table.packageSummary td.colFirst, table.overviewSummary th.colFirst {\r
+ width:25%;\r
+ vertical-align:middle;\r
+}\r
+/*\r
+Content styles\r
+*/\r
+.description pre {\r
+ margin-top:0;\r
+}\r
+.deprecatedContent {\r
+ margin:0;\r
+ padding:10px 0;\r
+}\r
+.docSummary {\r
+ padding:0;\r
+}\r
+/*\r
+Formatting effect styles\r
+*/\r
+.sourceLineNo {\r
+ color:green;\r
+ padding:0 30px 0 0;\r
+}\r
+h1.hidden {\r
+ visibility:hidden;\r
+ overflow:hidden;\r
+ font-size:.9em;\r
+}\r
+.block {\r
+ display:block;\r
+ margin:3px 0 0 0;\r
+}\r
+.strong {\r
+ font-weight:bold;\r
+}\r
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
+<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
+<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
+<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
+<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.gdbtrace.doc.user" type="4"/> </resources>}"/>
+<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
+<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/>
+<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.gdbtrace.doc.user"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.gdbtrace.doc.user/build.xml}"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
+<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
+</launchConfiguration>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.eclipse.tracecompass.gdbtrace.doc.user</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
+ <triggers>clean,full,incremental,</triggers>
+ <arguments>
+ <dictionary>
+ <key>LaunchConfigHandle</key>
+ <value><project>/.externalToolBuilders/Help Builder.launch</value>
+ </dictionary>
+ <dictionary>
+ <key>incclean</key>
+ <value>true</value>
+ </dictionary>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.ManifestBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.SchemaBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.pde.PluginNature</nature>
+ </natures>
+</projectDescription>
--- /dev/null
+eclipse.preferences.version=1
+encoding/<project>=UTF-8
--- /dev/null
+eclipse.preferences.version=1
+line.separator=\n
--- /dev/null
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-Vendor: %Bundle-Vendor
+Bundle-Version: 0.1.0.qualifier
+Bundle-Localization: plugin
+Bundle-SymbolicName: org.eclipse.tracecompass.gdbtrace.doc.user;singleton:=true
+Require-Bundle: org.eclipse.help
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+<title>About</title>
+</head>
+<body lang="EN-US">
+<h2>About This Content</h2>
+
+<p>June 5, 2006</p>
+<h3>License</h3>
+
+<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
+at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+For purposes of the EPL, "Program" will mean the Content.</p>
+
+<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
+being redistributed by another party ("Redistributor") and different terms and conditions may
+apply to your use of any object code in the Content. Check the Redistributor's license that was
+provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
+
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+/* following font face declarations need to be removed for DBCS */
+
+
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
+pre { font-family: Courier, monospace}
+
+/* end font face declarations */
+
+/* following font size declarations should be OK for DBCS */
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
+pre { font-size: 12pt}
+
+/* end font size declarations */
+
+body { background: #FFFFFF}
+h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
+h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
+h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
+h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
+h5 { font size: 13.5pt; }
+p { font-size: 12pt; }
+pre { margin-left: 6; font-size: 9pt }
+
+a:link { color: #006699 }
+a:visited { color: #996699 }
+a:hover { color: #006699 }
+
+ul { margin-top: 0; margin-bottom: 10 }
+li { margin-top: 0; margin-bottom: 0 }
+li p { margin-top: 0; margin-bottom: 0 }
+ol { margin-top: 0; margin-bottom: 10 }
+dl { margin-top: 0; margin-bottom: 10 }
+dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
+dd { margin-top: 0; margin-bottom: 0 }
+strong { font-weight: bold}
+em { font-style: italic}
+var { font-style: italic}
+div.revision { border-left-style: solid; border-left-width: thin;
+ border-left-color: #7B68EE; padding-left:5 }
+th { font-weight: bold }
+.hidden {
+ display: none;
+}
+
+/* Mike Behm's addition to the style sheet */
+.userinput { font-family: monospace; }
+.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
+.notetitle {
+ color: #000000;
+ font-family: helvetica, arial, sans-serif;
+ font-weight: bold;
+ }
+div.linux {display:none;}
+.firsterm {font-style:italic;}
+
+.typewriter {font-family:monospace;}
+.bold {font-weight:600;}
+.linethrough {text-decoration: line-through;}
+.underline {text-decoration: underline;}
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+bin.includes = META-INF/,\
+ about.html,\
+ book.css,\
+ doc/,\
+ plugin.properties,\
+ plugin.xml
+jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
+ platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
+src.includes = about.html
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (c) 2013 Ericsson
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<project name="org.eclipse.tracecompass.gdbtrace.doc.user" default="build">
+ <description>
+ Generate Eclipse help content for the Trace Compass GDB Tracepoint Analysis user guide
+ </description>
+
+ <!-- Set correct values -->
+ <property name="help.doc.url.base" value="http://wiki.eclipse.org" />
+ <property name="ug.path" value="Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide" />
+ <property name="ug.title" value="GDB Tracepoint Analysis User Guide" />
+
+ <path id="wikitext.tasks.classpath">
+ <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
+ <fileset dir="${osgi.syspath}" erroronmissingdir="false">
+ <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
+ <include name="com.google.guava_*.jar" />
+ </fileset>
+
+ <!-- For Maven builds: use the compile_classpath -->
+ <pathelement path="${compile_classpath}" />
+ </path>
+
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
+ <!-- Different location in more recent versions of Mylyn (Luna ?) -->
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
+
+ <target name="build" description="Generate Eclipse help content for the Linux Tools GDB Tracepoint Analysis User Guide">
+ <wikitext-to-eclipse-help markupLanguage="MediaWiki"
+ validate="true"
+ failonvalidationerror="true"
+ overwrite="true"
+ multipleOutputFiles="true"
+ navigationimages="true"
+ title="${ug.title}"
+ formatoutput="true"
+ helpPrefix="doc">
+ <fileset dir="./doc">
+ <include name="User-Guide.mediawiki" />
+ </fileset>
+ <stylesheet url="book.css" />
+ </wikitext-to-eclipse-help>
+ <antcall target="test" />
+ </target>
+
+ <target name="test" description="Verify that all of the HTML files are well-formed XML">
+ <!--
+ Don't bother with DTD validation: we only care if the files are well-formed.
+ We therefore provide an empty DTD
+ -->
+ <xmlvalidate lenient="true">
+ <fileset dir="doc">
+ <include name="**/*.html" />
+ </fileset>
+ <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
+ </xmlvalidate>
+ </target>
+
+ <!-- If you need a proxy for the "download" target, set it here -->
+ <!--
+ <setproxy proxyhost="host" proxyport="port"/>
+ -->
+
+ <target name="download" description="Download the current contents of the GDB Tracepoint Analysis User Guide from the Eclipse wiki">
+ <mediawiki-to-eclipse-help wikiBaseUrl="${help.doc.url.base}" title="${ug.title}" formatoutput="true" dest="." templateExcludes="*eclipseproject*">
+ <path name="${ug.path}" title="${ug.title}" generateToc="false" />
+ <stylesheet url="book.css" />
+ <pageAppendum>
+= Updating This Document =
+
+This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit
+http://wiki.eclipse.org/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide.
+ </pageAppendum>
+ </mediawiki-to-eclipse-help>
+ </target>
+
+ <target name ="clean" description="Delete all generated files">
+ <delete failonerror="false" includeemptydirs="true">
+ <!-- Files under doc/ (generated locally) -->
+ <fileset dir="doc" includes="**/*.html" />
+ <fileset dir="doc" includes="**/*.xml" />
+
+ <!-- Files downloaded from the Eclipse wiki -->
+ <fileset dir="Linux_Tools_Project" />
+ <fileset file="toc.xml" />
+ </delete>
+ </target>
+
+</project>
--- /dev/null
+*.html
+*.xml
--- /dev/null
+
+= Overview =
+
+The GDB Tracepoint Analysis feature is an extension to the Tracing and Monitoring Framework that allows the visualization and analysis of C/C++ tracepoint data collected by GDB and stored to a log file.
+
+= Getting Started =
+
+The feature can be installed from the Eclipse update site by selecting '''Linux Tools''' > '''GDB Tracepoint Analysis'''.
+
+The feature requires GDB version 7.2 or later to be installed on the local host. The executable program 'gdb' must be found in the path.
+
+= GDB Trace Perspective =
+
+To open the perspective, select '''Window''' > '''Open Perspective''' > '''Other...''' > '''GDB Trace'''.
+
+The perspective includes the following views by default:
+
+* '''Project Explorer''': This view shows the projects in the workspace and is used to create and manage Tracing projects.
+* '''Debug''': This view shows the running C/C++ Postmortem Debugger instances and displays the thread and stack trace associated with a tracepoint.
+* '''Trace Control''': This view shows the status of the debugger and allows navigation of trace records.
+* '''Console''': This view displays console output of the C/C++ Postmortem Debugger.
+
+The editor area contains the '''Events''' and '''C/C++''' editors when a GDB Trace is opened.
+
+[[Image:images/GDBTracePerspective.png]]
+
+= Collecting Tracepoint Data =
+
+Collecting the C/C++ tracepoint data is outside the scope of this feature. It can be done from the GDB command line or by using the CDT debug component within Eclipse. See the CDT FAQ entry in the [[#References | References]] section.
+
+= Importing Tracepoint Data =
+
+Some information in this section is redundant with the LTTng User Guide. For further details, see the LTTng User Guide entry in the [[#References | References]] section.
+
+== Creating a Tracing Project ==
+
+In the '''Project Explorer''' view, right-click and select '''New''' > '''Project...''' from the context menu. In the '''New Project''' dialog, select '''Tracing''' > '''Tracing Project''', click '''Next''', name your project and click '''Finish'''.
+
+== Importing a GDB Trace ==
+
+In your tracing project, right-click on the '''Traces''' folder and select '''Import...'''. Browse to, or enter, a source directory. Select the trace file in the tree. Optionally set the trace type to '''GDB : GDB Trace'''. Click '''Finish'''.
+
+Alternatively, the trace can be drag & dropped to the '''Traces''' folder from any external file manager.
+
+== Selecting the GDB Trace Type ==
+
+Right-click the imported trace in the '''Traces''' folder and choose '''Select Trace Type...''' > '''GDB''' > '''GDB Trace''' from the context menu. This step can be omitted if the trace type was selected at import.
+
+The trace will be updated with the GDB icon [[Image:images/gdb_icon16.png]].
+
+== Selecting the Trace Executable ==
+
+The executable file that created the tracepoint data must be identified so that the C/C++ Postmortem Debugger can be launched properly.
+
+Right-click the GDB trace in the '''Traces''' folder and choose '''Select Trace Executable...''' from the context menu. Browse to, or enter, the path of the executable file and press '''OK'''.
+
+The selected file must be recognized by GDB as an executable.
+
+= Visualizing Tracepoint Data =
+
+== Opening a GDB Trace ==
+
+In the '''Traces''' folder, double-click the GDB trace or right-click it and select '''Open''' from the context menu.
+
+The tracepoint data will be opened in an Events editor, and a C/C++ Postmortem Debugger instance will be launched.
+
+If available in the workspace, the source code corresponding to the first trace record will also be opened in a C/C++ editor.
+
+At this point it is recommended to relocate the Events editor outside of the default editor area, so that it is not hidden by the C/C++ editor.
+
+== Viewing Trace Data ==
+
+In the Events editor, a table is shown with one row for each trace record. The '''Trace Frame''' column shows the sequential trace record number. The '''Tracepoint''' column shows the number assigned by GDB at collection time for this tracepoint. The '''File''' column shows the file name, line number and method where the tracepoint was set. The '''Content''' column shows the data collected at run-time by the tracepoint.
+
+Searching and filtering can be done on any column by entering a regular expression in the column header.
+
+== Navigating the GDB Trace ==
+
+Trace records can be selected in the Events editor using the keyboard or mouse. The C/C++ Postmortem Debugger in the '''Debug''' view will be updated to show the stack trace of the current trace record.
+
+The trace can also be navigated from the '''Trace Control''' view by clicking the '''Next Trace Record''' or '''Previous Trace Record''' buttons. The Events editor and '''Debug''' views will be updated.
+
+= References =
+
+* [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide LTTng User Guide]
+* [http://wiki.eclipse.org/CDT/User/FAQ#How_can_I_trace_my_application_using_C.2FC.2B.2B_Tracepoints.3F CDT FAQ - How can I trace my application using C/C++ Tracepoints?]
+
+= Updating This Document =
+
+This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit [http://wiki.eclipse.org/index.php/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide http://wiki.eclipse.org/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide]
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass GDB Tracepoint Analysis User Guide
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (c) 2013 Ericsson.
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<plugin>
+<!-- This part should be in a documentation plugin -->
+<!-- Configure the help contribution for this plugin -->
+ <extension point="org.eclipse.help.toc">
+ <toc
+ file="doc/User-Guide-toc.xml"
+ primary="true" />
+ </extension>
+</plugin>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (c) 2013 Ericsson
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <artifactId>org.eclipse.tracecompass.doc</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.eclipse.tracecompass.gdbtrace.doc.user</artifactId>
+ <version>0.1.0-SNAPSHOT</version>
+ <packaging>eclipse-plugin</packaging>
+
+ <name>Trace Compass GDB Tracepoint Analysis User Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-documentation</id>
+ <phase>generate-sources</phase>
+ <configuration>
+ <echo>Generating GDB Tracepoint Analysis Help Files</echo>
+ <target>
+ <property name="compile_classpath" refid="maven.compile.classpath" />
+ <ant target="build" inheritRefs="true" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>clean-documentation</id>
+ <phase>clean</phase>
+ <configuration>
+ <echo>Cleaning up generated GDB Tracepoint Analysis Help Files</echo>
+ <target>
+ <ant target="clean" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-launcher</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-nodeps</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
+
+ <groupId>org.eclipse.tracecompass</groupId>
+</project>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
+<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
+<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
+<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
+<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.rcp.doc.user" type="4"/> </resources>}"/>
+<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
+<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/>
+<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.rcp.doc.user"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.rcp.doc.user/build.xml}"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
+<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
+</launchConfiguration>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.eclipse.tracecompass.rcp.doc.user</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
+ <triggers>clean,full,incremental,</triggers>
+ <arguments>
+ <dictionary>
+ <key>LaunchConfigHandle</key>
+ <value><project>/.externalToolBuilders/RCP Help Builder.launch</value>
+ </dictionary>
+ <dictionary>
+ <key>incclean</key>
+ <value>true</value>
+ </dictionary>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.ManifestBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.SchemaBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.pde.PluginNature</nature>
+ </natures>
+</projectDescription>
--- /dev/null
+eclipse.preferences.version=1
+encoding/<project>=UTF-8
--- /dev/null
+eclipse.preferences.version=1
+line.separator=\n
--- /dev/null
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-Vendor: %Bundle-Vendor
+Bundle-Version: 0.1.0.qualifier
+Bundle-Localization: plugin
+Bundle-SymbolicName: org.eclipse.tracecompass.rcp.doc.user;singleton:=true
+Require-Bundle: org.eclipse.help
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+<title>About</title>
+</head>
+<body lang="EN-US">
+<h2>About This Content</h2>
+
+<p>June 5, 2006</p>
+<h3>License</h3>
+
+<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
+at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+For purposes of the EPL, "Program" will mean the Content.</p>
+
+<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
+being redistributed by another party ("Redistributor") and different terms and conditions may
+apply to your use of any object code in the Content. Check the Redistributor's license that was
+provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
+
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+/* following font face declarations need to be removed for DBCS */
+
+
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
+pre { font-family: Courier, monospace}
+
+/* end font face declarations */
+
+/* following font size declarations should be OK for DBCS */
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
+pre { font-size: 12pt}
+
+/* end font size declarations */
+
+body { background: #FFFFFF}
+h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
+h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
+h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
+h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
+h5 { font size: 13.5pt; }
+p { font-size: 12pt; }
+pre { margin-left: 6; font-size: 9pt }
+
+a:link { color: #006699 }
+a:visited { color: #996699 }
+a:hover { color: #006699 }
+
+ul { margin-top: 0; margin-bottom: 10 }
+li { margin-top: 0; margin-bottom: 0 }
+li p { margin-top: 0; margin-bottom: 0 }
+ol { margin-top: 0; margin-bottom: 10 }
+dl { margin-top: 0; margin-bottom: 10 }
+dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
+dd { margin-top: 0; margin-bottom: 0 }
+strong { font-weight: bold}
+em { font-style: italic}
+var { font-style: italic}
+div.revision { border-left-style: solid; border-left-width: thin;
+ border-left-color: #7B68EE; padding-left:5 }
+th { font-weight: bold }
+.hidden {
+ display: none;
+}
+
+/* Mike Behm's addition to the style sheet */
+.userinput { font-family: monospace; }
+.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
+.notetitle {
+ color: #000000;
+ font-family: helvetica, arial, sans-serif;
+ font-weight: bold;
+ }
+div.linux {display:none;}
+.firsterm {font-style:italic;}
+
+.typewriter {font-family:monospace;}
+.bold {font-weight:600;}
+.linethrough {text-decoration: line-through;}
+.underline {text-decoration: underline;}
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+bin.includes = plugin.xml,\
+ META-INF/,\
+ about.html,\
+ plugin.properties,\
+ book.css,\
+ doc/
+jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
+ platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
+src.includes = about.html
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="org.eclipse.tracecompass.rcp.doc.user" default="build">
+ <description>
+ Generate Eclipse help content for the Trace Compass RCP user guide
+ </description>
+
+ <!-- Set correct values -->
+ <property name="help.doc.url.base" value="http://wiki.eclipse.org" />
+ <property name="ug.path" value="Linux_Tools_Project/Trace_Viewer/User_Guide" />
+ <property name="ug.title" value="Trace Compass RCP User Guide" />
+
+ <path id="wikitext.tasks.classpath">
+ <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
+ <fileset dir="${osgi.syspath}" erroronmissingdir="false">
+ <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
+ <include name="com.google.guava_*.jar" />
+ </fileset>
+
+ <!-- For Maven builds: use the compile_classpath -->
+ <pathelement path="${compile_classpath}" />
+ </path>
+
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
+ <!-- Different location in more recent versions of Mylyn (Luna ?) -->
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
+
+ <target name="build" description="Generate Eclipse help content for the Trace Compass RCP User Guide">
+ <wikitext-to-eclipse-help markupLanguage="MediaWiki"
+ validate="true"
+ failonvalidationerror="true"
+ overwrite="true"
+ multipleOutputFiles="true"
+ navigationimages="true"
+ title="${ug.title}"
+ formatoutput="true"
+ helpPrefix="doc">
+ <fileset dir="./doc">
+ <include name="User-Guide.mediawiki" />
+ </fileset>
+ <stylesheet url="book.css" />
+ </wikitext-to-eclipse-help>
+ <antcall target="test" />
+ </target>
+
+ <target name="test" description="Verify that all of the HTML files are well-formed XML">
+ <!--
+ Don't bother with DTD validation: we only care if the files are well-formed.
+ We therefore provide an empty DTD
+ -->
+ <xmlvalidate lenient="true">
+ <fileset dir="doc">
+ <include name="**/*.html" />
+ </fileset>
+ <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
+ </xmlvalidate>
+ </target>
+
+
+ <!-- If you need a proxy for the "download" target, set it here -->
+ <!--
+ <setproxy proxyhost="host" proxyport="port"/>
+ -->
+
+ <target name="download" description="Download the current contents of the LTTng User Guide from the Eclipse wiki">
+ <mediawiki-to-eclipse-help wikiBaseUrl="${help.doc.url.base}" title="${ug.title}" formatoutput="true" dest="." templateExcludes="*eclipseproject*">
+ <path name="${ug.path}" title="${ug.title}" generateToc="false" />
+ <stylesheet url="book.css" />
+ <pageAppendum>
+= Updating This Document =
+
+This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit
+http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide.
+ </pageAppendum>
+ </mediawiki-to-eclipse-help>
+ </target>
+
+ <target name ="clean" description="Delete all generated files">
+ <delete failonerror="false" includeemptydirs="true">
+ <!-- Files under doc/ (generated locally) -->
+ <fileset dir="doc" includes="**/*.html" />
+ <fileset dir="doc" includes="**/*.xml" />
+
+ <!-- Files downloaded from the Eclipse wiki -->
+ <fileset dir="Linux_Tools_Project" />
+ <fileset file="toc.xml" />
+ </delete>
+ </target>
+
+</project>
--- /dev/null
+*.html
+*.xml
--- /dev/null
+= Overview =
+The Trace Compass RCP version is a stand-alone application based on Eclipse's
+Rich Client Platform (RCP). The purpose of this is to provide a lightweight
+application to view and analyze traces. It includes most standard features found
+in the Trace Compass project.
+
+= Getting Started =
+To start the Trace Compass RCP, go to the directory where it is installed and
+then run the executable named '''tracecompass'''. During startup, the program
+will create, if necessary, an Eclipse workspace under the user's home directory
+with the name ''.tracecompass''. It also creates, if needed, a default tracing
+project called ''Tracing''.
+
+Now the application can be used as described in the regular User Guide. (see
+section [[#References | References]]).
+
+= Updating the application =
+The RCP is pre-configured to point to the update site of its release "track".
+For example, if you download a "nightly" RCP, it will update using that
+"nightly" update site. These settings are configurable in the preferences, but
+in most cases, the user should not have to change them.
+
+The program does not check automatically for updates. To check manually, you can
+click on '''Help''' -> '''Check for Updates'''. If updates are available, a
+standard Eclipse update dialog will offer their installation.
+
+= Opening a Trace =
+To open a trace, click on the '''File''' menu and select '''Open Trace...'''.
+A new dialog will show up for selecting a trace to open. Select a trace file
+and then click on '''OK'''. Note that for traces that are directories
+(such as Common Trace Format (CTF) traces) any file in the trace directory can
+be selected to open the trace. The auto detection algorithm will then validate
+the trace against all known trace types. If multiple trace types are valid, a
+trace type is chosen based on a confidence criteria. The validation process and
+the computation of the confidence level are trace type specific. After
+successful validation, the trace will be opened with the detected trace type.
+
+Alternatively the user can launch '''tracecompass''' with the command-line
+argument '''--open <trace-path>'''. The trace will then automatically open
+using the same algorithm than described above.
+
+In both of the above cases, the trace will be linked to the default project.
+
+= References =
+
+* [http://www.eclipse.org/tracecompass Trace Compass project]
+* [http://www.lttng.org/ LTTng project]
+
--- /dev/null
+###############################################################################
+# Copyright (c) 2013, 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Bernd Hufmann - Initial API and implementation
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass RCP User Guide
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin>
+<!-- This part should be in a documentation plugin -->
+<!-- Configure the help contribution for this plugin -->
+ <extension point="org.eclipse.help.toc">
+ <toc
+ file="doc/User-Guide-toc.xml"
+ primary="true" />
+ </extension>
+</plugin>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2011, Red Hat, Inc.
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <artifactId>org.eclipse.tracecompass.doc</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.eclipse.tracecompass.rcp.doc.user</artifactId>
+ <version>0.1.0-SNAPSHOT</version>
+ <packaging>eclipse-plugin</packaging>
+
+ <name>Trace Compass RCP User Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-documentation</id>
+ <phase>generate-sources</phase>
+ <configuration>
+ <echo>Generating Trace Compass RCP Help Files</echo>
+ <target>
+ <property name="compile_classpath" refid="maven.compile.classpath" />
+ <ant target="build" inheritRefs="true" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>clean-documentation</id>
+ <phase>clean</phase>
+ <configuration>
+ <echo>Cleaning up generated Trace Compass RCP Help Files</echo>
+ <target>
+ <ant target="clean" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-launcher</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-nodeps</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
+
+ <groupId>org.eclipse.tracecompass</groupId>
+</project>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
+<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
+<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
+<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
+<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.tmf.pcap.doc.user" type="4"/> </resources>}"/>
+<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS">
+<listEntry value="/org.eclipse.tracecompass.tmf.pcap.doc.user/build.xml"/>
+</listAttribute>
+<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES">
+<listEntry value="1"/>
+</listAttribute>
+<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
+<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.tmf.pcap.doc.user"/>
+<stringAttribute key="org.eclipse.jdt.launching.SOURCE_PATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.tmf.pcap.doc.user/build.xml}"/>
+<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
+<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
+<stringAttribute key="process_factory_id" value="org.eclipse.ant.ui.remoteAntProcessFactory"/>
+</launchConfiguration>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>org.eclipse.tracecompass.tmf.pcap.doc.user</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
+ <triggers>clean,full,incremental,</triggers>
+ <arguments>
+ <dictionary>
+ <key>LaunchConfigHandle</key>
+ <value><project>/.externalToolBuilders/org.eclipse.linuxtools.tmf.pcap.help build.xml [Builder].launch</value>
+ </dictionary>
+ <dictionary>
+ <key>incclean</key>
+ <value>true</value>
+ </dictionary>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.ManifestBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ <buildCommand>
+ <name>org.eclipse.pde.SchemaBuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.pde.PluginNature</nature>
+ <nature>org.eclipse.mylyn.wikitext.ui.wikiTextNature</nature>
+ </natures>
+</projectDescription>
--- /dev/null
+eclipse.preferences.version=1
+encoding/<project>=UTF-8
--- /dev/null
+eclipse.preferences.version=1
+line.separator=\n
--- /dev/null
+eclipse.preferences.version=1
+org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false
--- /dev/null
+Manifest-Version: 1.0
+Bundle-ManifestVersion: 2
+Bundle-Name: %Bundle-Name
+Bundle-Vendor: %Bundle-Vendor
+Bundle-Version: 0.1.0.qualifier
+Bundle-Localization: plugin
+Bundle-SymbolicName: org.eclipse.tracecompass.tmf.pcap.doc.user;singleton:=true
+Require-Bundle: org.eclipse.help
--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
+<title>About</title>
+</head>
+<body lang="EN-US">
+<h2>About This Content</h2>
+
+<p>June 5, 2006</p>
+<h3>License</h3>
+
+<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
+indicated below, the Content is provided to you under the terms and conditions of the
+Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
+at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
+For purposes of the EPL, "Program" will mean the Content.</p>
+
+<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
+being redistributed by another party ("Redistributor") and different terms and conditions may
+apply to your use of any object code in the Content. Check the Redistributor's license that was
+provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
+indicated below, the terms and conditions of the EPL still apply to any source code in the Content
+and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
+
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+/* following font face declarations need to be removed for DBCS */
+
+
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
+pre { font-family: Courier, monospace}
+
+/* end font face declarations */
+
+/* following font size declarations should be OK for DBCS */
+body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
+pre { font-size: 12pt}
+
+/* end font size declarations */
+
+body { background: #FFFFFF}
+h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
+h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
+h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
+h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
+h5 { font size: 13.5pt; }
+p { font-size: 12pt; }
+pre { margin-left: 6; font-size: 9pt }
+
+a:link { color: #006699 }
+a:visited { color: #996699 }
+a:hover { color: #006699 }
+
+ul { margin-top: 0; margin-bottom: 10 }
+li { margin-top: 0; margin-bottom: 0 }
+li p { margin-top: 0; margin-bottom: 0 }
+ol { margin-top: 0; margin-bottom: 10 }
+dl { margin-top: 0; margin-bottom: 10 }
+dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
+dd { margin-top: 0; margin-bottom: 0 }
+strong { font-weight: bold}
+em { font-style: italic}
+var { font-style: italic}
+div.revision { border-left-style: solid; border-left-width: thin;
+ border-left-color: #7B68EE; padding-left:5 }
+th { font-weight: bold }
+.hidden {
+ display: none;
+}
+
+/* Mike Behm's addition to the style sheet */
+.userinput { font-family: monospace; }
+.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
+.notetitle {
+ color: #000000;
+ font-family: helvetica, arial, sans-serif;
+ font-weight: bold;
+ }
+div.linux {display:none;}
+.firsterm {font-style:italic;}
+
+.typewriter {font-family:monospace;}
+.bold {font-weight:600;}
+.linethrough {text-decoration: line-through;}
+.underline {text-decoration: underline;}
--- /dev/null
+###############################################################################
+# Copyright (c) 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+bin.includes = plugin.xml,\
+ META-INF/,\
+ about.html,\
+ plugin.properties,\
+ book.css,\
+ doc/
+jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
+ platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
+src.includes = about.html
+
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="org.eclipse.tracecompass.tmf.pcap.doc.user" default="build" basedir=".">
+ <description>
+ Generate Eclipse help content for the Trace Compass Pcap User Guide
+ </description>
+
+ <property name="ug.title" value="Pcap Network Tracing User Guide" />
+
+ <path id="wikitext.tasks.classpath">
+ <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
+ <fileset dir="${osgi.syspath}" erroronmissingdir="false">
+ <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
+ <include name="com.google.guava_*.jar" />
+ </fileset>
+
+ <!-- For Maven builds: use the compile_classpath -->
+ <pathelement path="${compile_classpath}" />
+ </path>
+
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
+ <!-- Different location in more recent versions of Mylyn (Luna ?) -->
+ <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
+
+ <target name="build" description="Generate Eclipse help content for the Trace Compass Pcap User Guide">
+ <wikitext-to-eclipse-help markupLanguage="MediaWiki"
+ validate="true"
+ failonvalidationerror="true"
+ overwrite="true"
+ multipleOutputFiles="true"
+ navigationimages="true"
+ title="${ug.title}"
+ formatoutput="true"
+ helpPrefix="doc">
+ <fileset dir="doc">
+ <include name="User-Guide.mediawiki" />
+ </fileset>
+ <stylesheet url="book.css" />
+ </wikitext-to-eclipse-help>
+ <antcall target="test" />
+ </target>
+
+ <target name="test" description="Verify that all of the HTML files are well-formed XML">
+ <!--
+ Don't bother with DTD validation: we only care if the files are well-formed.
+ We therefore provide an empty DTD
+ -->
+ <xmlvalidate lenient="true">
+ <fileset dir="doc">
+ <include name="**/*.html" />
+ </fileset>
+ <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
+ </xmlvalidate>
+ </target>
+
+ <target name ="clean" description="Delete all generated files">
+ <delete failonerror="false">
+ <fileset dir="doc" includes="**/*.html" />
+ <fileset dir="doc" includes="**/*.xml" />
+ </delete>
+ </target>
+
+</project>
--- /dev/null
+*.html
+*.xml
--- /dev/null
+= Pcap Support Within TMF =
+
+TMF now supports the reading of libpcap files for network tracing. Those files contains packets that were seen on a network, have a .pcap or .cap extension and can be captured with tools like Wireshark/Tshark/Tcpdump. To open a libpcap trace, simply import it just like any other trace type and TMF will recognize the format. Open the imported trace to see the packets that were captured. For more information about generic features of TMF see the [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide User Guide].
+
+== Supported Protocols ==
+
+Currently, the Pcap integration in TMF can only recognize four protocols: Ethernet, Internet Protocol Version 4, TCP and UDP. In the future, more protocols will be added and supported. If you want to contribute, please see the “Adding a protocol” section in the [http://wiki.eclipse.org/Linux_Tools_Project/TMF/User_Guide TMF Developer Guide].
+
+== Network Tracing Perspective ==
+
+To help analyze the network traces, a new perspective has been created: the Network Tracing perspective. It looks a lot like Wireshark (since it is the de-facto standard) and contains all the views that are useful for network trace analysis. Those views are:
+* '''Event editor''': A high-level view of all the packets. It lists all the packets and gives basic information about them, like source, destination, timestamp, protocol, etc.
+* '''Properties View''': A low-level view of a particular packet. Once a packet is selected in the event editor, all its fields appear in the properties view.
+* '''Histogram View''': A distribution of the packets relative to time. This allows to identify the period where the network was the most solicited, for instance.
+* '''Statistics View''': A view of the different packet type present in the trace.
+* '''Colors View''': A view used to color the events in the event editor. This is useful for rapidly identifying packet type visually. By default, no event are colored.
+* '''Filter View''': A view used to filter the packets for easier analysis.
+* '''Stream List View''': A view that list all the stream present in the trace/experiment. A stream is a bidirectional flow of packets (a conversation) between two endpoints. An endpoint is either the source or the destination of a packet (which is protocol-dependent).
+
+To open the perspective, select '''Window''' > '''Open Perspective''' > '''Other...''' > '''Network Tracing'''.
+
+[[Image:images/networkTracingPerspective.png|The Network Tracing Perspective]]
+
+== Filtering On Subfield ==
+
+It is now possible to filter on subfields, which is really useful for pcap traces. To do so, in the field combo of the Filter View, start with a slash and type the subfield path by separating the different level with a slash. For instance, to get the Source IP Address of the Internet Protocol Version 4, type:
+
+''/Internet Protocol Version 4/Source IP Address''
+
+If a field name contains a real slash, type “\/” (backslash-slash) instead to make an uninterpreted slash. For instance, to get the field named “Process/Thread”, type:
+
+''/Process\/Thread''
+
+[[Image:images/subfieldFiltering.png|Example of filtering on subfields]]
+
+== Stream List View ==
+
+Most of the time, you want to analyze the conversation between two endpoints (a stream). The stream list view allows you to do just that, by isolating the interesting packets. The Stream List View is updated when a new pcap trace is opened and lists all the different streams present in the trace/experiment, for all the supported protocols. By right-clicking on a stream, you can follow a stream, which will send a TmfNewPacketStreamSignal that can be used by other views to run an analysis on the stream. You can also extract the stream as a filter, which will generate a filter based on the stream attributes. It is then possible to customize that filter and apply it on the event editor to get the interesting packets.
+
+[[Image:images/streamListView.png|Example of Stream List View]]
+
+== Limitations ==
+
+* No version check. It assumes the version is 2.4 (which is safe enough, since the format hasn't changed for 10+ years and is not supposed to change anytime soon.
+* All timestamps are assumed to be in GMT time.
+
+== References ==
+
+
+* [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide LTTng User Guide]
+* [http://wiki.eclipse.org/Linux_Tools_Project/TMF/User_Guide TMF Developer Guide]
+
--- /dev/null
+###############################################################################
+# Copyright (c) 2014 Ericsson
+#
+# All rights reserved. This program and the accompanying materials
+# are made available under the terms of the Eclipse Public License v1.0
+# which accompanies this distribution, and is available at
+# http://www.eclipse.org/legal/epl-v10.html
+#
+# Contributors:
+# Ericsson - Initial API and implementation
+###############################################################################
+
+Bundle-Vendor = Eclipse Trace Compass
+Bundle-Name = Trace Compass Pcap User Guide
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<plugin>
+<!-- This part should be in a documentation plugin -->
+<!-- Configure the help contribution for this plugin -->
+ <extension point="org.eclipse.help.toc">
+ <toc
+ file="doc/User-Guide-toc.xml"
+ primary="true" />
+ </extension>
+</plugin>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2014, Ericsson
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <artifactId>org.eclipse.tracecompass.doc</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.eclipse.tracecompass.tmf.pcap.doc.user</artifactId>
+ <version>0.1.0-SNAPSHOT</version>
+ <packaging>eclipse-plugin</packaging>
+
+ <name>Trace Compass Pcap User Guide</name>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>generate-documentation</id>
+ <phase>generate-sources</phase>
+ <configuration>
+ <echo>Generating Pcap Help Files</echo>
+ <target>
+ <property name="compile_classpath" refid="maven.compile.classpath" />
+ <ant target="build" inheritRefs="true" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ <execution>
+ <id>clean-documentation</id>
+ <phase>clean</phase>
+ <configuration>
+ <echo>Cleaning up generated Pcap Help Files</echo>
+ <target>
+ <ant target="clean" antfile="build.xml" />
+ </target>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-launcher</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.apache.ant</groupId>
+ <artifactId>ant-nodeps</artifactId>
+ <version>1.8.1</version>
+ </dependency>
+
+ </dependencies>
+ </plugin>
+ </plugins>
+ </build>
+
+ <groupId>org.eclipse.tracecompass</groupId>
+</project>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2015, Ericsson
+
+ All rights reserved. This program and the accompanying materials
+ are made available under the terms of the Eclipse Public License v1.0
+ which accompanies this distribution, and is available at
+ http://www.eclipse.org/legal/epl-v10.html
+-->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <prerequisites>
+ <maven>3.0</maven>
+ </prerequisites>
+
+ <parent>
+ <artifactId>org.eclipse.tracecompass</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>org.eclipse.tracecompass.doc</artifactId>
+ <groupId>org.eclipse.tracecompass</groupId>
+ <version>0.1.0-SNAPSHOT</version>
+ <packaging>pom</packaging>
+
+ <name>Trace Compass Documentation</name>
+
+ <modules>
+ <module>org.eclipse.tracecompass.doc.dev</module>
+ <module>org.eclipse.tracecompass.doc.user</module>
+ <module>org.eclipse.tracecompass.gdbtrace.doc.user</module>
+ <module>org.eclipse.tracecompass.rcp.doc.user</module>
+ <module>org.eclipse.tracecompass.tmf.pcap.doc.user</module>
+ </modules>
+
+</project>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
-<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
-<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
-<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.gdbtrace.help" type="4"/> </resources>}"/>
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/>
-<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.gdbtrace.help"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.gdbtrace.help/build.xml}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-</launchConfiguration>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
- <name>org.eclipse.tracecompass.gdbtrace.help</name>
- <comment></comment>
- <projects>
- </projects>
- <buildSpec>
- <buildCommand>
- <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
- <triggers>clean,full,incremental,</triggers>
- <arguments>
- <dictionary>
- <key>LaunchConfigHandle</key>
- <value><project>/.externalToolBuilders/Help Builder.launch</value>
- </dictionary>
- <dictionary>
- <key>incclean</key>
- <value>true</value>
- </dictionary>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.ManifestBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.SchemaBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- </buildSpec>
- <natures>
- <nature>org.eclipse.pde.PluginNature</nature>
- </natures>
-</projectDescription>
+++ /dev/null
-eclipse.preferences.version=1
-encoding/<project>=UTF-8
+++ /dev/null
-eclipse.preferences.version=1
-line.separator=\n
+++ /dev/null
-Manifest-Version: 1.0
-Bundle-ManifestVersion: 2
-Bundle-Name: %Bundle-Name
-Bundle-Vendor: %Bundle-Vendor
-Bundle-Version: 0.1.0.qualifier
-Bundle-Localization: plugin
-Bundle-SymbolicName: org.eclipse.tracecompass.gdbtrace.help;singleton:=true
-Require-Bundle: org.eclipse.help
+++ /dev/null
-This describes how to build the documentation found in the o.e.t.gdbtrace.help
-plugin.
-
-
-Your Eclipse environment first needs to have the "Mylyn Wikitext" plugin
-installed. It can be found in the default Eclipse repository, under
-"Collaboration".
-
-Once that is installed, you should be able to use the manual Eclipse builder to
-generate the doc : select the gdbtrace.help plugin and choose, in the top-menu,
-"Project -> Build Project".
-
-It uses the build.xml Ant script, but it's recommended to run it from within
-Eclipse, since the builder will pass some environment variables that the script
-needs.
-
-You might get a warning from build.properties because of a missing file. This
-file gets generated with the rest of the doc, so once you have run these steps
-(and refreshed the project if needed), the warning should disappear.
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
-<title>About</title>
-</head>
-<body lang="EN-US">
-<h2>About This Content</h2>
-
-<p>June 5, 2006</p>
-<h3>License</h3>
-
-<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
-indicated below, the Content is provided to you under the terms and conditions of the
-Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
-at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
-For purposes of the EPL, "Program" will mean the Content.</p>
-
-<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
-being redistributed by another party ("Redistributor") and different terms and conditions may
-apply to your use of any object code in the Content. Check the Redistributor's license that was
-provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
-indicated below, the terms and conditions of the EPL still apply to any source code in the Content
-and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
-
-</body>
-</html>
\ No newline at end of file
+++ /dev/null
-/* following font face declarations need to be removed for DBCS */
-
-
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
-pre { font-family: Courier, monospace}
-
-/* end font face declarations */
-
-/* following font size declarations should be OK for DBCS */
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
-pre { font-size: 12pt}
-
-/* end font size declarations */
-
-body { background: #FFFFFF}
-h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
-h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
-h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
-h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
-h5 { font size: 13.5pt; }
-p { font-size: 12pt; }
-pre { margin-left: 6; font-size: 9pt }
-
-a:link { color: #006699 }
-a:visited { color: #996699 }
-a:hover { color: #006699 }
-
-ul { margin-top: 0; margin-bottom: 10 }
-li { margin-top: 0; margin-bottom: 0 }
-li p { margin-top: 0; margin-bottom: 0 }
-ol { margin-top: 0; margin-bottom: 10 }
-dl { margin-top: 0; margin-bottom: 10 }
-dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
-dd { margin-top: 0; margin-bottom: 0 }
-strong { font-weight: bold}
-em { font-style: italic}
-var { font-style: italic}
-div.revision { border-left-style: solid; border-left-width: thin;
- border-left-color: #7B68EE; padding-left:5 }
-th { font-weight: bold }
-.hidden {
- display: none;
-}
-
-/* Mike Behm's addition to the style sheet */
-.userinput { font-family: monospace; }
-.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
-.notetitle {
- color: #000000;
- font-family: helvetica, arial, sans-serif;
- font-weight: bold;
- }
-div.linux {display:none;}
-.firsterm {font-style:italic;}
-
-.typewriter {font-family:monospace;}
-.bold {font-weight:600;}
-.linethrough {text-decoration: line-through;}
-.underline {text-decoration: underline;}
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-bin.includes = META-INF/,\
- about.html,\
- book.css,\
- doc/,\
- plugin.properties,\
- plugin.xml
-jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
- platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
-src.includes = about.html
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (c) 2013 Ericsson
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<project name="org.eclipse.tracecompass.gdbtrace.help" default="build">
- <description>
- Generate Eclipse help content for the Linux Tools GDB Tracepoint Analysis user guide
- </description>
-
- <!-- Set correct values -->
- <property name="help.doc.url.base" value="http://wiki.eclipse.org" />
- <property name="ug.path" value="Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide" />
- <property name="ug.title" value="GDB Tracepoint Analysis User Guide" />
-
- <path id="wikitext.tasks.classpath">
- <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
- <fileset dir="${osgi.syspath}" erroronmissingdir="false">
- <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
- <include name="com.google.guava_*.jar" />
- </fileset>
-
- <!-- For Maven builds: use the compile_classpath -->
- <pathelement path="${compile_classpath}" />
- </path>
-
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
- <!-- Different location in more recent versions of Mylyn (Luna ?) -->
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
-
- <target name="build" description="Generate Eclipse help content for the Linux Tools GDB Tracepoint Analysis User Guide">
- <wikitext-to-eclipse-help markupLanguage="MediaWiki"
- validate="true"
- failonvalidationerror="true"
- overwrite="true"
- multipleOutputFiles="true"
- navigationimages="true"
- title="${ug.title}"
- formatoutput="true"
- helpPrefix="doc">
- <fileset dir="./doc">
- <include name="User-Guide.mediawiki" />
- </fileset>
- <stylesheet url="book.css" />
- </wikitext-to-eclipse-help>
- <antcall target="test" />
- </target>
-
- <target name="test" description="Verify that all of the HTML files are well-formed XML">
- <!--
- Don't bother with DTD validation: we only care if the files are well-formed.
- We therefore provide an empty DTD
- -->
- <xmlvalidate lenient="true">
- <fileset dir="doc">
- <include name="**/*.html" />
- </fileset>
- <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
- </xmlvalidate>
- </target>
-
- <!-- If you need a proxy for the "download" target, set it here -->
- <!--
- <setproxy proxyhost="host" proxyport="port"/>
- -->
-
- <target name="download" description="Download the current contents of the GDB Tracepoint Analysis User Guide from the Eclipse wiki">
- <mediawiki-to-eclipse-help wikiBaseUrl="${help.doc.url.base}" title="${ug.title}" formatoutput="true" dest="." templateExcludes="*eclipseproject*">
- <path name="${ug.path}" title="${ug.title}" generateToc="false" />
- <stylesheet url="book.css" />
- <pageAppendum>
-= Updating This Document =
-
-This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit
-http://wiki.eclipse.org/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide.
- </pageAppendum>
- </mediawiki-to-eclipse-help>
- </target>
-
- <target name ="clean" description="Delete all generated files">
- <delete failonerror="false" includeemptydirs="true">
- <!-- Files under doc/ (generated locally) -->
- <fileset dir="doc" includes="**/*.html" />
- <fileset dir="doc" includes="**/*.xml" />
-
- <!-- Files downloaded from the Eclipse wiki -->
- <fileset dir="Linux_Tools_Project" />
- <fileset file="toc.xml" />
- </delete>
- </target>
-
-</project>
+++ /dev/null
-*.html
-*.xml
+++ /dev/null
-
-= Overview =
-
-The GDB Tracepoint Analysis feature is an extension to the Tracing and Monitoring Framework that allows the visualization and analysis of C/C++ tracepoint data collected by GDB and stored to a log file.
-
-= Getting Started =
-
-The feature can be installed from the Eclipse update site by selecting '''Linux Tools''' > '''GDB Tracepoint Analysis'''.
-
-The feature requires GDB version 7.2 or later to be installed on the local host. The executable program 'gdb' must be found in the path.
-
-= GDB Trace Perspective =
-
-To open the perspective, select '''Window''' > '''Open Perspective''' > '''Other...''' > '''GDB Trace'''.
-
-The perspective includes the following views by default:
-
-* '''Project Explorer''': This view shows the projects in the workspace and is used to create and manage Tracing projects.
-* '''Debug''': This view shows the running C/C++ Postmortem Debugger instances and displays the thread and stack trace associated with a tracepoint.
-* '''Trace Control''': This view shows the status of the debugger and allows navigation of trace records.
-* '''Console''': This view displays console output of the C/C++ Postmortem Debugger.
-
-The editor area contains the '''Events''' and '''C/C++''' editors when a GDB Trace is opened.
-
-[[Image:images/GDBTracePerspective.png]]
-
-= Collecting Tracepoint Data =
-
-Collecting the C/C++ tracepoint data is outside the scope of this feature. It can be done from the GDB command line or by using the CDT debug component within Eclipse. See the CDT FAQ entry in the [[#References | References]] section.
-
-= Importing Tracepoint Data =
-
-Some information in this section is redundant with the LTTng User Guide. For further details, see the LTTng User Guide entry in the [[#References | References]] section.
-
-== Creating a Tracing Project ==
-
-In the '''Project Explorer''' view, right-click and select '''New''' > '''Project...''' from the context menu. In the '''New Project''' dialog, select '''Tracing''' > '''Tracing Project''', click '''Next''', name your project and click '''Finish'''.
-
-== Importing a GDB Trace ==
-
-In your tracing project, right-click on the '''Traces''' folder and select '''Import...'''. Browse to, or enter, a source directory. Select the trace file in the tree. Optionally set the trace type to '''GDB : GDB Trace'''. Click '''Finish'''.
-
-Alternatively, the trace can be drag & dropped to the '''Traces''' folder from any external file manager.
-
-== Selecting the GDB Trace Type ==
-
-Right-click the imported trace in the '''Traces''' folder and choose '''Select Trace Type...''' > '''GDB''' > '''GDB Trace''' from the context menu. This step can be omitted if the trace type was selected at import.
-
-The trace will be updated with the GDB icon [[Image:images/gdb_icon16.png]].
-
-== Selecting the Trace Executable ==
-
-The executable file that created the tracepoint data must be identified so that the C/C++ Postmortem Debugger can be launched properly.
-
-Right-click the GDB trace in the '''Traces''' folder and choose '''Select Trace Executable...''' from the context menu. Browse to, or enter, the path of the executable file and press '''OK'''.
-
-The selected file must be recognized by GDB as an executable.
-
-= Visualizing Tracepoint Data =
-
-== Opening a GDB Trace ==
-
-In the '''Traces''' folder, double-click the GDB trace or right-click it and select '''Open''' from the context menu.
-
-The tracepoint data will be opened in an Events editor, and a C/C++ Postmortem Debugger instance will be launched.
-
-If available in the workspace, the source code corresponding to the first trace record will also be opened in a C/C++ editor.
-
-At this point it is recommended to relocate the Events editor outside of the default editor area, so that it is not hidden by the C/C++ editor.
-
-== Viewing Trace Data ==
-
-In the Events editor, a table is shown with one row for each trace record. The '''Trace Frame''' column shows the sequential trace record number. The '''Tracepoint''' column shows the number assigned by GDB at collection time for this tracepoint. The '''File''' column shows the file name, line number and method where the tracepoint was set. The '''Content''' column shows the data collected at run-time by the tracepoint.
-
-Searching and filtering can be done on any column by entering a regular expression in the column header.
-
-== Navigating the GDB Trace ==
-
-Trace records can be selected in the Events editor using the keyboard or mouse. The C/C++ Postmortem Debugger in the '''Debug''' view will be updated to show the stack trace of the current trace record.
-
-The trace can also be navigated from the '''Trace Control''' view by clicking the '''Next Trace Record''' or '''Previous Trace Record''' buttons. The Events editor and '''Debug''' views will be updated.
-
-= References =
-
-* [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide LTTng User Guide]
-* [http://wiki.eclipse.org/CDT/User/FAQ#How_can_I_trace_my_application_using_C.2FC.2B.2B_Tracepoints.3F CDT FAQ - How can I trace my application using C/C++ Tracepoints?]
-
-= Updating This Document =
-
-This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit [http://wiki.eclipse.org/index.php/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide http://wiki.eclipse.org/Linux_Tools_Project/GDB_Tracepoint_Analysis/User_Guide]
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-#Properties file for org.eclipse.tracecompass.gdbtrace.help
-Bundle-Vendor = Eclipse Trace Compass
-Bundle-Name = Trace Compass GDB Tracepoint Analysis Help Plug-in
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (c) 2013 Ericsson.
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<plugin>
-<!-- This part should be in a documentation plugin -->
-<!-- Configure the help contribution for this plugin -->
- <extension point="org.eclipse.help.toc">
- <toc
- file="doc/User-Guide-toc.xml"
- primary="true" />
- </extension>
-</plugin>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (c) 2013 Ericsson
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <artifactId>org.eclipse.tracecompass</artifactId>
- <groupId>org.eclipse.tracecompass</groupId>
- <version>0.1.0-SNAPSHOT</version>
- </parent>
-
- <artifactId>org.eclipse.tracecompass.gdbtrace.help</artifactId>
- <version>0.1.0-SNAPSHOT</version>
- <packaging>eclipse-plugin</packaging>
-
- <name>Trace Compass GDB Tracepoint Analysis Help Plug-in</name>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-antrun-plugin</artifactId>
- <executions>
- <execution>
- <id>generate-documentation</id>
- <phase>generate-sources</phase>
- <configuration>
- <echo>Generating GDB Tracepoint Analysis Help Files</echo>
- <target>
- <property name="compile_classpath" refid="maven.compile.classpath" />
- <ant target="build" inheritRefs="true" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- <execution>
- <id>clean-documentation</id>
- <phase>clean</phase>
- <configuration>
- <echo>Cleaning up generated GDB Tracepoint Analysis Help Files</echo>
- <target>
- <ant target="clean" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- </executions>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-launcher</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-nodeps</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- </dependencies>
- </plugin>
- </plugins>
- </build>
-
- <groupId>org.eclipse.tracecompass</groupId>
-</project>
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.gdbtrace.help"
+ id="org.eclipse.tracecompass.gdbtrace.doc.user"
download-size="0"
install-size="0"
version="0.0.0"/>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
-<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
-<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
-<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.help" type="4"/> </resources>}"/>
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/>
-<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.help"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.help/build.xml}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-</launchConfiguration>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
- <name>org.eclipse.tracecompass.help</name>
- <comment></comment>
- <projects>
- </projects>
- <buildSpec>
- <buildCommand>
- <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
- <triggers>clean,full,incremental,</triggers>
- <arguments>
- <dictionary>
- <key>LaunchConfigHandle</key>
- <value><project>/.externalToolBuilders/Lttng Help Build.launch</value>
- </dictionary>
- <dictionary>
- <key>incclean</key>
- <value>true</value>
- </dictionary>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.ManifestBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.SchemaBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- </buildSpec>
- <natures>
- <nature>org.eclipse.pde.PluginNature</nature>
- </natures>
-</projectDescription>
+++ /dev/null
-eclipse.preferences.version=1
-encoding/<project>=UTF-8
+++ /dev/null
-eclipse.preferences.version=1
-line.separator=\n
+++ /dev/null
-Manifest-Version: 1.0
-Bundle-ManifestVersion: 2
-Bundle-Name: %Bundle-Name
-Bundle-Vendor: %Bundle-Vendor
-Bundle-Version: 0.1.0.qualifier
-Bundle-Localization: plugin
-Bundle-SymbolicName: org.eclipse.tracecompass.help;singleton:=true
-Require-Bundle: org.eclipse.help
+++ /dev/null
-This describes how to build the documentation found in the o.e.t.help plugin.
-
-
-Your Eclipse environment first needs to have the "Mylyn Wikitext" plugin
-installed. It can be found in the default Eclipse repository, under
-"Collaboration".
-
-Once that is installed, you should be able to use the manual Eclipse builder to
-generate the doc : select the lttng.help plugin and choose, in the top-menu,
-"Project -> Build Project".
-
-It uses the build.xml Ant script, but it's recommended to run it from within
-Eclipse, since the builder will pass some environment variables that the script
-needs.
-
-You might get a warning from build.properties because of a missing file. This
-file gets generated with the rest of the doc, so once you have run these steps
-(and refreshed the project if needed), the warning should disappear.
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
-<title>About</title>
-</head>
-<body lang="EN-US">
-<h2>About This Content</h2>
-
-<p>June 5, 2006</p>
-<h3>License</h3>
-
-<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
-indicated below, the Content is provided to you under the terms and conditions of the
-Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
-at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
-For purposes of the EPL, "Program" will mean the Content.</p>
-
-<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
-being redistributed by another party ("Redistributor") and different terms and conditions may
-apply to your use of any object code in the Content. Check the Redistributor's license that was
-provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
-indicated below, the terms and conditions of the EPL still apply to any source code in the Content
-and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
-
-</body>
-</html>
\ No newline at end of file
+++ /dev/null
-/* following font face declarations need to be removed for DBCS */
-
-
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
-pre { font-family: Courier, monospace}
-
-/* end font face declarations */
-
-/* following font size declarations should be OK for DBCS */
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
-pre { font-size: 12pt}
-
-/* end font size declarations */
-
-body { background: #FFFFFF}
-h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
-h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
-h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
-h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
-h5 { font size: 13.5pt; }
-p { font-size: 12pt; }
-pre { margin-left: 6; font-size: 9pt }
-
-a:link { color: #006699 }
-a:visited { color: #996699 }
-a:hover { color: #006699 }
-
-ul { margin-top: 0; margin-bottom: 10 }
-li { margin-top: 0; margin-bottom: 0 }
-li p { margin-top: 0; margin-bottom: 0 }
-ol { margin-top: 0; margin-bottom: 10 }
-dl { margin-top: 0; margin-bottom: 10 }
-dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
-dd { margin-top: 0; margin-bottom: 0 }
-strong { font-weight: bold}
-em { font-style: italic}
-var { font-style: italic}
-div.revision { border-left-style: solid; border-left-width: thin;
- border-left-color: #7B68EE; padding-left:5 }
-th { font-weight: bold }
-.hidden {
- display: none;
-}
-
-/* Mike Behm's addition to the style sheet */
-.userinput { font-family: monospace; }
-.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
-.notetitle {
- color: #000000;
- font-family: helvetica, arial, sans-serif;
- font-weight: bold;
- }
-div.linux {display:none;}
-.firsterm {font-style:italic;}
-
-.typewriter {font-family:monospace;}
-.bold {font-weight:600;}
-.linethrough {text-decoration: line-through;}
-.underline {text-decoration: underline;}
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-bin.includes = plugin.xml,\
- META-INF/,\
- about.html,\
- plugin.properties,\
- book.css,\
- doc/,\
- reference/
-jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
- platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
-src.includes = about.html
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="org.eclipse.tracecompass.help" default="build">
- <description>
- Generate Eclipse help content for the Linux Tools LTTng user guide
- </description>
-
- <!-- Set correct values -->
- <property name="help.doc.url.base" value="http://wiki.eclipse.org" />
- <property name="ug.path" value="Linux_Tools_Project/LTTng2/User_Guide" />
- <property name="ug.title" value="LTTng Plug-in User Guide" />
-
- <path id="wikitext.tasks.classpath">
- <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
- <fileset dir="${osgi.syspath}" erroronmissingdir="false">
- <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
- <include name="com.google.guava_*.jar" />
- </fileset>
-
- <!-- For Maven builds: use the compile_classpath -->
- <pathelement path="${compile_classpath}" />
- </path>
-
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
- <!-- Different location in more recent versions of Mylyn (Luna ?) -->
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
-
- <target name="build" description="Generate Eclipse help content for the Linux Tools LTTng User Guide">
- <wikitext-to-eclipse-help markupLanguage="MediaWiki"
- validate="true"
- failonvalidationerror="true"
- overwrite="true"
- multipleOutputFiles="true"
- navigationimages="true"
- title="${ug.title}"
- formatoutput="true"
- helpPrefix="doc">
- <fileset dir="./doc">
- <include name="User-Guide.mediawiki" />
- </fileset>
- <stylesheet url="book.css" />
- </wikitext-to-eclipse-help>
- <antcall target="test" />
- </target>
-
- <target name="test" description="Verify that all of the HTML files are well-formed XML">
- <!--
- Don't bother with DTD validation: we only care if the files are well-formed.
- We therefore provide an empty DTD
- -->
- <xmlvalidate lenient="true">
- <fileset dir="doc">
- <include name="**/*.html" />
- </fileset>
- <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
- </xmlvalidate>
- </target>
-
-
- <!-- If you need a proxy for the "download" target, set it here -->
- <!--
- <setproxy proxyhost="host" proxyport="port"/>
- -->
-
- <target name="download" description="Download the current contents of the LTTng User Guide from the Eclipse wiki">
- <mediawiki-to-eclipse-help wikiBaseUrl="${help.doc.url.base}" title="${ug.title}" formatoutput="true" dest="." templateExcludes="*eclipseproject*">
- <path name="${ug.path}" title="${ug.title}" generateToc="false" />
- <stylesheet url="book.css" />
- <pageAppendum>
-= Updating This Document =
-
-This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit
-http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide.
- </pageAppendum>
- </mediawiki-to-eclipse-help>
- </target>
-
- <target name ="clean" description="Delete all generated files">
- <delete failonerror="false" includeemptydirs="true">
- <!-- Files under doc/ (generated locally) -->
- <fileset dir="doc" includes="**/*.html" />
- <fileset dir="doc" includes="**/*.xml" />
-
- <!-- Files downloaded from the Eclipse wiki -->
- <fileset dir="Linux_Tools_Project" />
- <fileset file="toc.xml" />
- </delete>
- </target>
-
-</project>
+++ /dev/null
-*.html
-*.xml
+++ /dev/null
-
-= Overview =
-
-LTTng (Linux Trace Toolkit, next generation) is a highly efficient tracing tool for Linux that can be used to track down kernel and application performance issues as well as troubleshoot problems involving multiple concurrent processes and threads. It consists of a set of kernel modules, daemons - to collect the raw tracing data - and a set of tools to control, visualize and analyze the generated data. It also provides support for user space application instrumentation.
-For more information about LTTng, refer to the project [http://lttng.org site]
-
-'''Note''': This User Guide covers the integration of the latest LTTng (up to v2.4) in Eclipse.
-
-== About Tracing ==
-
-Tracing is a troubleshooting technique used to understand the behavior of an instrumented application by collecting information on its execution path. A tracer is the software used for tracing. Tracing can be used to troubleshoot a wide range of bugs that are otherwise extremely challenging. These include, for example, performance problems in complex parallel systems or real-time systems.
-
-Tracing is similar to logging: it consists in recording events that happen in a system at selected execution locations. However, compared to logging, it is generally aimed at developers and it usually records low-level events at a high rate. Tracers can typically generate thousands of events per second. The generated traces can easily contain millions of events and have sizes from many megabytes to tens of gigabytes. Tracers must therefore be optimized to handle a lot of data while having a small impact on the system.
-
-Traces may include events from the operating system kernel (IRQ handler entry/exit, system call entry/exit, scheduling activity, network activity, etc). They can also consists of application events (a.k.a UST - User Space Tracing) or a mix of the two.
-
-For the maximum level of detail, tracing events may be viewed like a log file. However, trace analyzers and viewers are available to derive useful information from the raw data coupled with knowledge of the traced program. These programs must be specially designed to handle quickly the enormous amount of data a trace may contain.
-
-== LTTng integration ==
-
-The LTTng plug-in for Eclipse provides an Eclipse integration for the control of the LTTng tracer as well as fetching and visualization of the traces produced. It also provides the foundation for user-defined analysis tools.
-
-The LTTng Eclipse plug-in provides the following views:
-
-* ''Project'' - an extension to the standard Eclipse Project view tailored for tracing projects
-* ''Control'' - to control the tracer and configure the tracepoints
-* ''Events'' - a versatile view that presents the raw events in tabular format with support for searching, filtering and bookmarking
-* ''Statistics'' - a view that that provides simple statistics on event occurrences by type
-* ''Histogram'' - a view that displays the event density with respect to time in traces
-
-These views can be extended or tailored for specific trace types (e.g. kernel, HW, user app).
-
-At present, the LTTng Eclipse plug-in for Eclipse supports the following kernel-oriented views:
-
-* ''Control Flow'' - to visualize processes state transitions
-* ''Resources'' - to visualize system resources state transitions
-* ''CPU usage'' - to visualize the usage of the processor with respect to the time in traces
-
-It also supports the following User Space traces views:
-
-* ''Memory Usage'' - to visualize the memory usage per thread with respect to time in the traces
-* ''Call Stack'' - to visualize the call stack's evolution over time
-
-Although the control and fetching parts are targeted at the LTTng tracer, the underlying framework can also be used to process any trace that complies with the ''Common Trace Format'' ([http://www.efficios.com/ctf CTF]). CTF specifies a very efficient and compact binary trace format that is meant to be application-, architecture-, and language-agnostic.
-
-== Features ==
-
-The LTTng Eclipse plug-in has a number of features to allow efficient handling of very large traces (and sets of large traces):
-
-* Support for arbitrarily large traces (larger than available memory)
-* Support for correlating multiple time-ordered traces
-* Support for zooming down to the nanosecond on any part of a trace or set of traces
-* Views synchronization of currently selected time or time range, and window time range
-* Efficient searching and filtering of events
-* Support for trace bookmarks
-* Support for importing and exporting trace packages
-
-There is also support for the integration of non-LTTng trace types:
-
-* Built-in CTF parser
-* Dynamic creation of customized parsers (for XML and text traces)
-* Dynamic creation of customized state systems (from XML files)
-* Dynamic creation of customized views (from XML files)
-
-= Installation =
-
-This section describes the installation of the LTTng tracer and the LTTng Eclipse plug-ins as well as their dependencies.
-
-== LTTng Tracer ==
-
-While the Eclipse plug-ins can run on the standard Eclipse platforms (Linux, Mac, Windows), the LTTng tracer and its accompanying tools run on Linux.
-
-The tracer and tools have been available for download in Ubuntu since 12.04. They can easily be installed with the following command:
-
-<pre>
- > sudo apt-get install lttng-tools
-</pre>
-
-For other distributions, older Ubuntu distributions, or the latest, bleeding edge LTTng tracer, please refer to the [http://lttng.org/download LTTng website] for installation information.
-
-'''Note''': The LTTng tracer (and accompanying tools) is required only if you want to create your own traces (the usual case). If you intend to simply analyze existing traces then it is not necessary to install the tracer.
-
-== LTTng Eclipse Plug-ins ==
-
-The easiest way to install the LTTng plug-ins for Eclipse is through the Software Updates and Add-ons menu. For information on how to use this menu, refer to this [http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site link].
-
-The LTTng plug-ins are structured as a stack of features/plug-ins as following:
-
-* '''CTF''' - A CTF parser that can also be used as a standalone component
-** ''Feature'': org.eclipse.linuxtools.ctf
-** ''Plug-ins'': org.eclipse.linuxtools.ctf.core, org.eclipse.linuxtools.ctf.parser
-
-* '''State System Core''' - State system for TMF
-** ''Plug-ins'': org.eclipse.linuxtools.statesystem.core
-
-* '''TMF''' - ''Tracing and Monitoring Framework'' a framework for generic trace processing
-** ''Feature'': org.eclipse.linuxtools.tmf
-** ''Plug-ins'': org.eclipse.linuxtools.tmf.core, org.eclipse.linuxtools.tmf.ui. org.eclipse.linuxtools.tmf.analysis.xml.core, org.eclipse.linuxtools.tmf.analysis.xml.ui
-
-* '''CTF support for TMF''' - CTF support for the TMF Feature
-** ''Feature'': org.eclipse.linuxtools.tmf.ctf
-** ''Plug-ins'': org.eclipse.linuxtools.tmf.ctf.core
-
-* '''LTTng''' - The wrapper for the LTTng tracer control. Can be used for kernel or application tracing.
-** ''Feature'': org.eclipse.linuxtools.lttng2.control
-** ''Plug-ins'': org.eclipse.linuxtools.lttng2.control.core, org.eclipse.linuxtools.lttng2.control.ui
-
-* '''LTTng Kernel''' - Analysis components specific to Linux kernel traces
-** ''Feature'': org.eclipse.linuxtools.lttng2.kernel
-** ''Plug-ins'': org.eclipse.linuxtools.lttng2.kernel.core, org.eclipse.linuxtools.lttng2.kernel.ui
-
-* '''LTTng UST''' - Analysis components specific to Linux userspace traces
-** ''Feature'': org.eclipse.linuxtools.lttng2.ust
-** ''Plug-ins'': org.eclipse.linuxtools.lttng2.ust.core, org.eclipse.linuxtools.lttng2.ust.ui
-
-== LTTng Eclipse Dependencies ==
-
-The Eclipse LTTng controls the LTTng tracer through an ''ssh'' connection, if the tracer is running locally it can use or bypass the ''ssh'' connection.
-
-Therefore, the target system (where the tracer runs) needs to run an ''ssh'' server as well as ''sftp'' server (for file transfer) to which you have permission to connect.
-
-On the host side (where Eclipse is running), you also need to have Eclipse Remote Services installed to handle the SSH connection and transport. The Remote Services can be installed the standard way (''Help'' > ''Install New Software...'' > ''General Purpose Tools'' > ''Remote Services'').
-
-== Installation Verification ==
-
-If you do not have any, sample LTTng traces can be found here [http://lttng.org/download]. At the bottom of the page there is a link to some sample LTTng 2.0 kernel traces. The trace needs to be uncompressed to be read.
-
-Here are the quick steps to verify that your installation is functional:
-
-* Start Eclipse
-* Open the LTTng perspective
-* Create a Tracing project
-** Right-click in the Project view and select "New Project"
-** Enter the name of your project (e.g. "MyLTTngProject")
-** The project will be created. It will contain 2 empty folders: "Traces" and "Experiments"
-* Open a sample trace
-** Right-click on the newly created project "Traces" folder and select "Open Trace..."
-** Navigate to the sample LTTng trace that you want to visualize and select any file in the trace folder
-** The newly imported trace should appear under the Traces folder
-* Visualize the trace
-** Expand the Traces folder
-** Double-click on the trace
-** The trace should load and the views be populated
-
-If an error message is displayed, you might want to double-check that the trace type is correctly set (right-click on the trace and "Select Trace Type...").
-
-Refer to [[#Tracing Perspective]] for detailed description of the views and their usage.
-
-= LTTng =
-
-== Tracing Perspective ==
-
-The '''Tracing''' perspective is part of the '''Tracing and Monitoring Framework (TMF)''' and groups the following views:
-
-* [[#Project_View | Project View]]
-* [[#Events_Editor | Events Editor]]
-* [[#Histogram_View | Histogram View]]
-* [[#Statistics_View | Statistics View]]
-
-The views are synchronized i.e. selecting an event, a timestamp, a time range, etc will update the other views accordingly.
-
-[[Image:images/TracingPerspective.png]]
-
-The perspective can be opened from the Eclipse Open Perspective dialog ('''Window > Open Perspective... > Other''').
-
-[[Image:images/ShowTracingPerspective.png]]
-
-In addition to these views, the '''Tracing and Monitoring Framework (TMF)''' feature provides a set of generic tracing specific views, such as:
-
-* [[#Colors_View | Colors View]]
-* [[#Filters_View | Filters View]]
-* [[#Time_Chart_View | Time Chart View]]
-* [[#State_System_Explorer_View | State System Explorer View]]
-* [[#Call_Stack_View | Call Stack View]]
-
-The framework also supports user creation of [[#Custom_Parsers | Custom Parsers]].
-
-To open one of the above '''Tracing''' views, use the Eclipse Show View dialog ('''Window > Show View > Other...'''). Then select the relevant view from the '''Tracing''' category.
-
-[[Image:images/ShowTracingViews.png]]
-
-Additionally, the '''LTTng''' feature provides an '''LTTng Tracer Control''' functionality. It comes with a dedicated '''Control View'''.
-
-* [[#LTTng_Tracer_Control | LTTng Tracer Control]]
-
-== Project View ==
-
-The project view is the standard Eclipse Project Explorer. '''Tracing''' projects are well integrated in the Eclipse's Common Navigator Framework. The Project Explorer shows '''Tracing''' project with a small "T" decorator in the upper right of the project folder icon.
-
-=== Creating a Tracing Project ===
-
-A new '''Tracing''' project can be created using the New Tracing Project wizard. To create a new '''Tracing''' select '''File > New > Project...''' from the main menu bar or alternatively form the context-sensitive menu (click with right mouse button in the '''Project Explorer'''.
-
-The first page of project wizard will open.
-
-[[Image:images/NewTracingProjectPage1.png]]
-
-In the list of project categories, expand category '''Tracing''' and select '''Tracing Project''' and the click on '''Next >'''. A second page of the wizard will show. Now enter the a name in the field '''Project Name''', select a location if required and the press on '''Finish'''.
-
-[[Image:images/NewTracingProjectPage2.png]]
-
-A new project will appear in the '''Project Explorer''' view.
-
-[[Image:images/NewProjectExplorer.png]]
-
-Tracing projects have two sub-folders: '''Traces''' which holds the individual traces, and '''Experiments''' which holds sets of traces that we want to correlate.
-
-=== Importing Traces to the Project ===
-
-The '''Traces''' folder holds the set of traces available for a tracing project. It can optionally contain a tree of trace folders to organize traces into sub-folders. The following chapters will explain different ways to import traces to the '''Traces''' folder of a tracing project.
-
-* [[#Opening a Trace | Opening a Trace]]
-* [[#Importing | Importing]]
-* [[#Drag and Drop | Drag and Drop]]
-
-==== Opening a Trace ====
-
-To open a trace, right-click on a target trace folder and select '''Open Trace...'''.
-
-[[Image:images/OpenTraceFile.png]]
-
-A new dialog will show for selecting a trace to open. Select a trace file and then click on '''OK'''. Note that for traces that are directories (such as Common Trace Format (CTF) traces) any file in the trace directory can be selected to open the trace. Now, the trace viewer will attempt to detect the trace types of the selected trace. The auto detection algorithm will validate the trace against all known trace types. If multiple trace types are valid, a trace type is chosen based on a confidence criteria. The validation process and the computation of the confidence level are trace type specific. After successful validation the trace will be linked into the selected target trace folder and then opened with the detected trace type.
-
-Note that a trace type is an extension point of the '''Tracing and Monitoring Framework (TMF)'''. Depending on the which features are loaded, the list of available trace types can vary.
-
-==== Importing ====
-
-To import a set of traces to a trace folder, right-click on the target folder and select '''Import...''' from the context-sensitive menu.
-
-[[Image:images/ProjectImportTraceAction.png]]
-
-At this point, the '''Import Trace Wizard''' will show for selecting traces to import. By default, it shows the correct destination directory where the traces will be imported to. Now, specify the location of the traces in the '''Root directory'''. For that click on the button '''Browse''', browse the media to the location of the traces and click on '''OK'''. Then select the traces to import in the list of files and folders.
-
-Traces can also be imported from an archive file such as a zip or a tar file by selecting the '''Select archive file''' option then by clicking '''Browse'''. Then select the traces to import in the list of files and folders as usual.
-
-Optionally, select the '''Trace Type''' from the drop-down menu. If '''Trace Type''' is set to '''<Automatic Detection>''', the wizard will attempt to detect the trace types of the selected files. The automatic detection algorithm validates a trace against all known trace types. If multiple trace types are valid, a trace type is chosen based on a confidence criteria. The validation process and the computation of the confidence level are trace type specific. Optionally, '''Import unrecognized traces''' can be selected to import trace files that could not be automatically detected by '''<Automatic Detection>'''.
-
-Select or deselect the checkboxes for '''Overwrite existing trace without warning''', '''Create links in workspace''' and '''Preserve folder structure'''. When all options are configured, click on '''Finish'''.
-
-Note that traces of certain types (e.g. LTTng Kernel) are actually a composite of multiple channel traces grouped under a folder. Either the folder or its files can be selected to import the trace.
-
-The option '''Preserve folder structure''' will create, if necessary, the structure of folders relative to (and excluding) the selected '''Root directory''' (or '''Archive file''') into the target trace folder.
-
-[[Image:images/ProjectImportTraceDialog.png]]
-
-If a trace already exists with the same name in the target trace folder, the user can choose to rename the imported trace, overwrite the original trace or skip the trace. When rename is chosen, a number is appended to the trace name, for example smalltrace becomes smalltrace(2).
-
-[[Image:images/ProjectImportTraceDialogRename.png]]
-
-If one selects '''Rename All''', '''Overwrite All''' or '''Skip All''' the choice will be applied for all traces with a name conflict.
-
-Upon successful importing, the traces will be stored in the target trace folder. If a trace type was associated to a trace, then the corresponding icon will be displayed. If no trace type is detected the default editor icon associated with this file type will be displayed. Linked traces will have a little arrow as decorator on the right bottom corner.
-
-Note that trace type is an extension point of the '''Tracing and Monitoring Framework (TMF)'''. Depending on the which features are loaded, the list of trace types can vary.
-
-Alternatively, one can open the '''Import...''' menu from the '''File''' main menu, then select '''Tracing''' > '''Trace Import''' and click on '''Next >'''.
-
-[[Image:images/ProjectImportWizardSelect.png]]
-
-At this point, the '''Import Trace Wizard''' will show. To import traces to the tracing project, follow the instructions that were described above.
-
-==== Drag and Drop ====
-
-Traces can be also be imported to a project by dragging from another tracing project and dropping to the project's target trace folder. The trace will be copied and the trace type will be set.
-
-Any resource can be dragged and dropped from a non-tracing project, and any file or folder can be dragged from an external tool, into a tracing project's trace folder. The resource will be copied or imported as a new trace and it will be attempted to detect the trace types of the imported resource. The automatic detection algorithm validates a trace against all known trace types. If multiple trace types are valid, a trace type is chosen based on a confidence criteria. The validation process and the computation of the confidence level are trace type specific. If no trace type is detected the user needs to set the trace type manually.
-
-To import the trace as a link, use the platform-specific key modifier while dragging the source trace. A link will be created in the target project to the trace's location on the file system.
-
-If a folder containing traces is dropped on a trace folder, the full directory structure will be copied or linked to the target trace folder. The trace type of the contained traces will not be auto-detected.
-
-It is also possible to drop a trace, resource, file or folder into an existing experiment. If the item does not already exist as a trace in the project's trace folder, it will first be copied or imported, then the trace will be added to the experiment.
-
-=== Trace Package Exporting and Importing ===
-
-A trace package is an archive file that contains the trace itself and can also contain its bookmarks and its supplementary files. Including supplementary files in the package can improve performance of opening an imported trace but at the expense of package size.
-
-==== Exporting ====
-
-The '''Export Trace Package Wizard''' allows users to select a trace and export its files and bookmarks to an archive on a media.
-
-The '''Traces''' folder holds the set of traces available for a tracing project. To export traces contained in the '''Traces''' folder, one can open the '''Export...''' menu from the '''File''' main menu. Then select '''Trace Package Export'''
-
-[[Image:images/tracePackageImages/fileExport.png]]
-
-At this point, the '''Trace Package Export''' is opened. The project containing the traces has to be selected first then the traces to be exported.
-
-[[Image:images/tracePackageImages/chooseTrace.png]]
-
-One can also open the wizard and skip the first page by expanding the project, selecting traces or trace folders under the '''Traces''' folder, then right-clicking and selecting the '''Export Trace Package...''' menu item in the context-sensitive menu.
-
-[[Image:images/tracePackageImages/exportSelectedTrace.png]]
-
-Next, the user can choose the content to export and various format options for the resulting file.
-
-[[Image:images/tracePackageImages/exportPackage.png]]
-
-The '''Trace''' item is always selected and represents the files that constitute the trace. The '''Supplementary files''' items represent files that are typically generated when a trace is opened by the viewer. Sharing these files can speed up opening a trace dramatically but also increases the size of the exported archive file. The ''Size'' column can help to decide whether or not to include these files. Lastly, by selecting '''Bookmarks''', the user can export all the bookmarks so that they can be shared along with the trace.
-
-The '''To archive file''' field is used to specify the location where to save the resulting archive.
-
-The '''Options''' section allows the user to choose between a tar archive or a zip archive. Compression can also be toggled on or off.
-
-When Finish button is clicked, the package is generated and saved to the media. The folder structure of the selected traces relative to the '''Traces''' folder is preserved in the trace package.
-
-==== Importing ====
-
-The '''Import Trace Package Wizard''' allows users to select a previously exported trace package from their media and import the content of the package in the workspace.
-
-The '''Traces''' folder holds the set of traces for a tracing project. To import a trace package to the '''Traces''' folder, one can open the '''Import...''' menu from the '''File''' main menu. Then select '''Trace Package Import'''.
-
-[[Image:images/tracePackageImages/fileImport.png]]
-
-One can also open the wizard by expanding the project name, right-clicking on a target folder under the '''Traces''' folder then selecting '''Import Trace Package...''' menu item in the context-sensitive menu.
-
-[[Image:images/tracePackageImages/importTraceFolder.png]]
-
-At this point, the '''Trace Package Import Wizard''' is opened.
-
-[[Image:images/tracePackageImages/importPackage.png]]
-
-The '''From archive file''' field is used to specify the location of the trace package to export. The user can choose the content to import in the tree.
-
-If the wizard was opened using the File menu, the destination project has to be selected in the '''Into project''' field.
-
-When Finish is clicked, the trace is imported in the target folder. The folder structure from the trace package is restored in the target folder.
-
-=== Selecting a Trace Type ===
-
-If no trace type was selected a trace type has to be associated to a trace before it can be opened. To select a trace type select the relevant trace and click the right mouse button. In the context-sensitive menu, select '''Select Trace Type...''' menu item. A sub-menu will show will all available trace type categories. From the relevant category select the required trace type. The examples, below show how to select the '''Common Trace Format''' types '''LTTng Kernel''' and '''Generic CTF trace'''.
-
-[[Image:images/SelectLTTngKernelTraceType.png]]
-
-[[Image:images/SelectGenericCTFTraceType.png]]
-
-After selecting the trace type, the trace icon will be updated with the corresponding trace type icon.
-
-[[Image:images/ExplorerWithAssociatedTraceType.png]]
-
-=== Opening a Trace or Experiment ===
-
-A trace or experiment can be opened by double-clicking the left mouse button on the trace or experiment in the '''Project Explorer''' view. Alternatively, select the trace or experiment in the in the '''Project Explorer''' view and click the right mouse button. Then select '''Open''' menu item of the context-sensitive menu. If there is no trace type set for a file resource then the file will be opened in the default editor associated with this file type.
-
-[[Image:images/OpenTraceAction.png]]
-
-When opening a trace or experiment, all currently opened views which are relevant for the corresponding trace type will be updated.
-
-If a trace resource is a file (and not a directory), then the '''Open With''' menu item is available in the context-sensitive menu and can be used to open the trace source file with any applicable internal or external editor. In that case the trace will not be processed by the tracing application.
-
-=== Creating a Experiment ===
-
-An experiment consists in an arbitrary number of aggregated traces for purpose of correlation. In the degenerate case, an experiment can consist of a single trace. The experiment provides a unified, time-ordered stream of the individual trace events.
-
-To create an experiment, select the folder '''Experiments''' and click the right mouse button. Then select '''New...'''.
-
-[[Image:images/NewExperimentAction.png]]
-
-A new display will open for entering the experiment name. Type the name of the experiment in the text field '''Experiment Name''' and the click on '''OK'''.
-
-[[Image:images/NewExperimentDialog.png]]
-
-=== Selecting Traces for an Experiment ===
-
-After creating an experiment, traces need to be added to the experiment. To select traces for an experiment select the newly create experiment and click the right mouse button. Select '''Select Traces...''' from the context sensitive menu.
-
-[[Image:images/SelectTracesAction.png]]
-
-A new dialog box will open with a list of available traces. The filter text box can be used to quickly find traces. Use buttons '''Select All''' or '''Deselect All''' to select or deselect all traces. Select the traces to add from the list and then click on '''Finish'''.
-
-[[Image:images/SelectTracesDialog.png]]
-
-Now the selected traces will be linked to the experiment and will be shown under the '''Experiments''' folder.
-
-[[Image:images/ExplorerWithExperiment.png]]
-
-Alternatively, traces can be added to an experiment using [[#Drag_and_Drop | Drag and Drop]].
-
-=== Removing Traces from an Experiment ===
-
-To remove one or more traces for an experiment select the trace(s) to remove under the Experiment folder and click the right mouse button. Select '''Remove''' from the context sensitive menu.
-
-[[Image:images/RemoveTracesAction.png]]
-
-After that the selected trace(s) are removed from the experiment. Note that the traces are still in the '''Traces''' folder.
-
-=== Renaming a Trace or Experiment ===
-
-Traces and Experiment can be renamed from the '''Project Explorer''' view. To rename a trace or experiment select the relevant trace and click the right mouse button. Then select '''Rename...''' from the context sensitive menu. The trace or experiment needs to be closed in order to do this operation.
-
-[[Image:images/RenameTraceAction.png]]
-
-A new dialog box will show for entering a new name. Enter a new trace or experiment name respectively in the relevant text field and click on '''OK'''. If the new name already exists the dialog box will show an error and a different name has to be entered.
-
-[[Image:images/RenameTraceDialog.png]]
-
-[[Image:images/RenameExperimentDialog.png]]
-
-After successful renaming the new name will show in the '''Project Explorer'''. In case of a trace all reference links to that trace will be updated too. Note that linked traces only changes the display name, the underlying trace resource will stay the original name.
-
-Note that all supplementary files will be also handled accordingly (see also [[#Deleting Supplementary Files | Deleting Supplementary Files]]).
-
-=== Copying a Trace or Experiment ===
-
-To copy a trace or experiment select the relevant trace or experiment in the '''Project Explorer''' view and click the right mouse button. Then select '''Copy...''' from the context sensitive menu.
-
-[[Image:images/CopyTraceAction.png]]
-
-A new dialog box will show for entering a new name. Enter a new trace or experiment name respectively in the relevant text field and click on '''OK'''. If the new name already exists the dialog box will show an error and a different name has to be entered.
-
-[[Image:images/CopyTraceDialog.png]]
-
-[[Image:images/CopyExperimentDialog.png]]
-
-After successful copy operation the new trace or experiment respectively will show in the '''Project Explorer'''. In case of a linked trace, the copied trace will be a link to the original trace too.
-
-Note that the directory for all supplementary files will be copied, too. (see also [[#Deleting Supplementary Files | Deleting Supplementary Files]]).
-
-=== Deleting a Trace or Experiment ===
-
-To delete a trace or experiment select the relevant trace or experiment in the '''Project Explorer''' view and click the right mouse button. Then select '''Delete...''' from the context sensitive menu. The trace or experiment needs to be closed in order to do this operation.
-
-[[Image:images/DeleteExperimentAction.png]]
-
-A confirmation dialog box will open. To perform the deletion press '''OK''' otherwise select '''Cancel'''.
-
-[[Image:images/DeleteExperimentConfirmationDialog.png]]
-
-After successful operation the selected trace or experiment will be removed from the project. In case of a linked trace only the link will be removed. The actual trace resource remain on the disk.
-
-Note that the directory for all supplementary files will be deleted, too. (see also [[#Deleting Supplementary Files | Deleting Supplementary Files]]).
-
-=== Deleting Supplementary Files ===
-
-Supplementary files are by definition trace specific files that accompany a trace. These file could be temporary files, persistent indexes or any other persistent data files created by the LTTng integration in Eclipse during parsing a trace. For the LTTng 2.0 trace viewer a persistent state history of the Linux Kernel is created and is stored under the name '''stateHistory.ht'''. The statistics for all traces are stored under '''statistics.ht'''. Other state systems may appear in the same folder as more custom views are added.
-
-All supplementary file are hidden from the user and are handled internally by the TMF. However, there is a possibility to delete the supplementary files so that there are recreated when opening a trace.
-
-To delete all supplementary files from one or many traces and experiments, select the relevant traces and experiments in the '''Project Explorer''' view and click the right mouse button. Then select the '''Delete Supplementary Files...''' menu item from the context-sensitive menu.
-
-[[Image:images/DeleteSupplementaryFilesAction.png]]
-
-A new dialog box will open with a list of supplementary files, grouped under the trace or experiment they belong to. Select the file(s) to delete from the list and press '''OK'''. The traces and experiments that need to be closed in order to do this operation will automatically be closed.
-
-[[Image:images/DeleteSupplementaryFilesDialog.png]]
-
-=== Link with Editor ===
-
-The tracing projects support the feature '''Link With Editor''' of the Project Explorer view. With this feature it is now possible to<br/>
-* select a trace element in the Project Explorer view and the corresponding [[#Events Editor | Events Editor]] will get focus if the relevant trace is open.
-* select an [[#Events Editor | Events Editor]] and the corresponding trace element will be highlighted in the Project Explorer view.
-
-To enable or disable this feature toggle the '''Link With Editor''' button of the Project Explorer view as shown below.
-
-[[Image:images/TMF_LinkWithEditor.png]]
-
-== Events Editor ==
-
-The Events editor shows the basic trace data elements (events) in a tabular format. The editors can be dragged in the editor area so that several traces may be shown side by side. These traces are synchronized by timestamp.
-
-[[Image:images/LTTng2EventsEditor.png]]
-
-The header displays the current trace (or experiment) name.
-
-Being part of the '''Tracing and Monitoring''' Framework, the default table displays the following fields:
-
-* '''Timestamp''': the event timestamp
-* '''Source''': the source of the event
-* '''Type''': the event type and localization
-* '''Reference''' the event reference
-* '''Content''': the raw event content
-
-The first row of the table is the header row a.k.a. the Search and Filter row.
-
-The highlighted event is the ''current event'' and is synchronized with the other views. If you select another event, the other views will be updated accordingly. The properties view will display a more detailed view of the selected event.
-
-An event range can be selected by holding the '''Shift''' key while clicking another event or using any of the cursor keys ('''Up'''', '''Down''', '''PageUp''', '''PageDown''', '''Home''', '''End'''). The first and last events in the selection will be used to determine the current selected time range for synchronization with the other views.
-
-[[Image:images/LTTng2EventProperties.png]]
-
-The Events editor can be closed, disposing a trace. When this is done, all the views displaying the information will be updated with the trace data of the next event editor tab. If all the editor tabs are closed, then the views will display their empty states.
-
-=== Searching and Filtering ===
-
-Searching and filtering of events in the table can be performed by entering matching conditions in one or multiple columns in the header row (the first row below the column header).
-
-To toggle between searching and filtering, click on the 'search' ([[Image:images/TmfEventSearch.gif]]) or 'filter' ([[Image:images/TmfEventFilter.gif]]) icon in the header row's left margin, or right-click on the header row and select '''Show Filter Bar''' or '''Show Search Bar''' in the context menu.
-
-To apply a matching condition to a specific column, click on the column's header row cell, type in a [http://download.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html regular expression] and press the '''ENTER''' key. You can also enter a simple text string and it will be automatically be replaced with a 'contains' regular expression.
-
-When matching conditions are applied to two or more columns, all conditions must be met for the event to match (i.e. 'and' behavior).
-
-To clear all matching conditions in the header row, press the '''DEL''' key.
-
-==== Searching ====
-
-When a searching condition is applied to the header row, the table will select the next matching event starting from the top currently displayed event. Wrapping will occur if there is no match until the end of the trace.
-
-All matching events will have a 'search match' icon in their left margin. Non-matching events will be dimmed.
-
-[[Image:images/DefaultTmfEvents-Search.png]]
-
-Pressing the '''ENTER''' key will search and select the next matching event. Pressing the '''SHIFT-ENTER''' key will search and select the previous matching event. Wrapping will occur in both directions.
-
-Press '''ESC''' to cancel an ongoing search.
-
-Press '''DEL''' to clear the header row and reset all events to normal.
-
-==== Filtering ====
-
-When a filtering condition is entered in the head row, the table will clear all events and fill itself with matching events as they are found from the beginning of the trace.
-
-A status row will be displayed before and after the matching events, dynamically showing how many matching events were found and how many events were processed so far. Once the filtering is completed, the status row icon in the left margin will change from a 'stop' to a 'filter' icon.
-
-[[Image:images/DefaultTmfEvents-Filter.png]]
-
-Press '''ESC''' to stop an ongoing filtering. In this case the status row icon will remain as a 'stop' icon to indicate that not all events were processed.
-
-Press '''DEL''' or right-click on the table and select '''Clear Filters''' from the context menu to clear the header row and remove the filtering. All trace events will be now shown in the table. Note that the currently selected event will remain selected even after the filter is removed.
-
-You can also search on the subset of filtered events by toggling the header row to the Search Bar while a filter is applied. Searching and filtering conditions are independent of each other.
-
-==== Bookmarking ====
-
-Any event of interest can be tagged with a bookmark.
-
-To add a bookmark, double-click the left margin next to an event, or right-click the margin and select '''Add bookmark...'''. Alternatively use the '''Edit''' > '''Add bookmark...''' menu. Edit the bookmark description as desired and press '''OK'''.
-
-The bookmark will be displayed in the left margin, and hovering the mouse over the bookmark icon will display the description in a tooltip.
-
-The bookmark will be added to the '''Bookmarks''' view. In this view the bookmark description can be edited, and the bookmark can be deleted. Double-clicking the bookmark or selecting '''Go to''' from its context menu will open the trace or experiment and go directly to the event that was bookmarked.
-
-To remove a bookmark, double-click its icon, select '''Remove Bookmark''' from the left margin context menu, or select '''Delete''' from the Bookmarks view.
-
-[[Image:images/Bookmarks.png]]
-
-=== Event Source Lookup ===
-
-For CTF traces using specification v1.8.2 or above, information can optionally be embedded in the trace to indicate the source of a trace event. This is accessed through the event context menu by right-clicking on an event in the table.
-
-==== Source Code ====
-
-If a source file is available in the trace for the selected event, the item '''Open Source Code''' is shown in the context menu. Selecting this menu item will attempt to find the source file in all opened projects in the workspace. If multiple candidates exist, a selection dialog will be shown to the user. The selected source file will be opened, at the correct line, in its default language editor. If no candidate is found, an error dialog is shown displaying the source code information.
-
-==== EMF Model ====
-
-If an EMF model URI is available in the trace for the selected event, the item '''Open Model Element''' is shown in the context menu. Selecting this menu item will attempt to open the model file in the project specified in the URI. The model file will be opened in its default model editor. If the model file is not found, an error dialog is shown displaying the URI information.
-
-=== Exporting To Text ===
-It is possible to export the content of the trace to a text file based on the columns displayed in the events table. If a filter (see '''[[#Filtering| Filtering]]''') was defined prior exporting only events that match the filter will be exported to the file. To export the trace to text, press the right mouse button on the events table. A context-sensitive menu will show. Select the '''Export To Text...''' menu option. A file locater dialog will open. Fill in the file name and location and then press on '''OK'''. A window with a progress bar will open till the export is finished.
-
-''Note'': The columns in the text file are separated by tabs.
-
-=== Collapsing of Repetitive Events ===
-The implementation for collapsing of repetitive events is trace type specific and is only available for certain trace types. For example, a trace type could allow collapsing of consecutive events that have the same event content but not the same timestamp. If a trace type supports this feature then it is possible to select the '''Collapse Events''' menu item after pressing the right mouse button in the table.
-
-When the collapsing of events is executing, the table will clear all events and fill itself with all relevant events. If the collapse condition is met, the first column of the table will show the number of times this event was repeated consecutively.
-
-[[Image:images/TablePreCollapse.png]]
-
-A status row will be displayed before and after the events, dynamically showing how many non-collapsed events were found and how many events were processed so far. Once the collapsing is completed, the status row icon in the left margin will change from a 'stop' to a 'filter' icon.
-
-[[Image:images/TablePostCollapse.png]]
-
-To clear collapsing, press the right mouse button in the table and select menu item '''Clear Filters''' in the context sensitive menu. ''Note'' that collapsing is also removed when another filter is applied to the table.
-
-== Histogram View ==
-
-The Histogram View displays the trace events distribution with respect to time. When streaming a trace, this view is dynamically updated as the events are received.
-
-[[Image:images/HistogramView.png]]
-
-The '''Hide Lost Events''' toggle button [[Image:images/hide_lost_events.gif]] in the local toolbar allows to hide the bars of lost events. When the button is selected it can be toggled again to show the lost events.
-
-The '''Activate Trace Coloring''' toggle button [[Image:images/show_hist_traces.gif]] in the local toolbar allows to use separate colors for each trace of an experiment. Note that this feature is not available if your experiment contains more than twenty two traces. When activated, a legend is displayed at the bottom on the histogram view.
-
-On the top left, there are three text controls:
-
-* '''Selection Start''': Displays the start time of the current selection
-* '''Selection End''': Displays the end time of the current selection
-* '''Window Span''': Displays the current zoom window size in seconds
-
-The controls can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly. To modify both selection times simultaneously, press the link icon [[Image:images/link.gif]] which disables the '''Selection End''' control input.
-
-The large (full) histogram, at the bottom, shows the event distribution over the whole trace or set of traces. It also has a smaller semi-transparent orange window, with a cross-hair, that shows the current zoom window.
-
-The smaller (zoom) histogram, on top right, corresponds to the current zoom window, a sub-range of the event set.
-
-The x-axis of each histogram corresponds to the event timestamps. The start time and end time of the histogram range is displayed. The y-axis shows the maximum number of events in the corresponding histogram bars.
-
-The vertical blue line(s) show the current selection time (or range). If applicable, the region in the selection range will be shaded.
-
-The mouse can be used to control the histogram:
-
-* '''Left-click''': Set a selection time
-* '''Left-drag''': Set a selection range
-* '''Shift-left-click or drag''': Extend or shrink the selection range
-
-* '''Middle-click or Ctrl-left-click''': Center the zoom window on mouse (full histogram only)
-* '''Middle-drag or Ctrl-left-drag''': Move the zoom window
-
-* '''Right-drag''': Set the zoom window
-* '''Shift-right-click or drag''': Extend or shrink the zoom window (full histogram only)
-
-* '''Mouse wheel up''': Zoom in
-* '''Mouse wheel down''': Zoom out
-
-Hovering the mouse over an histogram bar pops up an information window that displays the start/end time of the corresponding bar, as well as the number of events (and lost events) it represents. If the mouse is over the selection range, the selection span in seconds is displayed.
-
-In each histogram, the following keys are handled:
-
-* '''Left Arrow''': Moves the current event to the previous non-empty bar
-* '''Right Arrow''': Moves the current event to the next non-empty bar
-* '''Home''': Sets the current time to the first non-empty bar
-* '''End''': Sets the current time to the last non-empty histogram bar
-* '''Plus (+)''': Zoom in
-* '''Minus (-)''': Zoom out
-
-== Statistics View ==
-
-The Statistics View displays the various event counters that are collected when analyzing a trace. The data is organized per trace. After opening a trace, the element '''Statistics''' is added under the '''Tmf Statistics Analysis''' tree element in the Project Explorer. To open the view, double-click the '''Statistics''' tree element. Alternatively, select '''Statistics''' under '''Tracing''' within the '''Show View''' window ('''Window''' -> '''Show View''' -> '''Other...'''). This view shows 3 columns: ''Level'' ''Events total'' and ''Events in selected time range''. After parsing a trace the view will display the number of events per event type in the second column and in the third, the currently selected time range's event type distribution is shown. The cells where the number of events are printed also contain a colored bar with a number that indicates the percentage of the event count in relation to the total number of events. The statistics is collected for the whole trace. This view is part of the '''Tracing and Monitoring Framework (TMF)''' and is generic. It will work for any trace type extensions. For the LTTng 2.0 integration the Statistics view will display statistics as shown below.:
-
-[[Image:images/LTTng2StatisticsView.png]]
-
-By default, the statistics use a state system, therefore will load very quickly once the state system is written to the disk as a supplementary file.
-
-== Colors View ==
-
-[[Image:images/ColorsView.png]]
-
-The Colors view allows the user to define a prioritized list of color settings.
-
-A color setting associates a foreground and background color (used in any events table), and a tick color (used in the Time Chart view), with an event filter.
-
-In an events table, any event row that matches the event filter of a color setting will be displayed with the specified foreground and background colors. If the event matches multiple filters, the color setting with the highest priority will be used.
-
-The same principle applies to the event tick colors in the Time Chart view. If a tick represents many events, the tick color of the highest priority matching event will be used.
-
-Color settings can be inserted, deleted, reordered, imported and exported using the buttons in the Colors view toolbar. Changes to the color settings are applied immediately, and are persisted to disk.
-
-== Filters View ==
-
-[[Image:images/FiltersView.png]]
-
-The Filters view allows the user to define preset filters that can be applied to any events table.
-
-The filters can be more complex than what can be achieved with the filter header row in the events table. The filter is defined in a tree node structure, where the node types can be any of '''EVENTTYPE''', '''AND''', '''OR''', '''CONTAINS''', '''EQUALS''', '''MATCHES''' or '''COMPARE'''. Some nodes types have restrictions on their possible children in the tree.
-
-The '''EVENTTYPE''' node filters against the event type of the trace as defined in a plug-in extension or in a custom parsers. When used, any child node will have its field combo box restricted to the possible fields of that event type.
-
-The '''AND''' node applies the logical ''and'' condition on all of its children. All children conditions must be true for the filter to match. A ''not'' operator can be applied to invert the condition.
-
-The '''OR''' node applies the logical ''or'' condition on all of its children. At least one children condition must be true for the filter to match. A ''not'' operator can be applied to invert the condition.
-
-The '''CONTAINS''' node matches when the specified event ''field'' value contains the specified ''value'' string. A ''not'' operator can be applied to invert the condition. The condition can be case sensitive or insensitive.
-
-The '''EQUALS''' node matches when the specified event ''field'' value equals exactly the specified ''value'' string. A ''not'' operator can be applied to invert the condition. The condition can be case sensitive or insensitive.
-
-The '''MATCHES''' node matches when the specified event ''field'' value matches against the specified ''regular expression''. A ''not'' operator can be applied to invert the condition.
-
-The '''COMPARE''' node matches when the specified event ''field'' value compared with the specified ''value'' gives the specified ''result''. The result can be set to ''smaller than'', ''equal'' or ''greater than''. The type of comparison can be numerical, alphanumerical or based on time stamp. A ''not'' operator can be applied to invert the condition.
-
-Filters can be added, deleted, imported and exported using the buttons in the Filters view toolbar. The nodes in the view can be Cut (Ctrl-X), Copied (Ctrl-C) and Pasted (Ctrl-V) by using the buttons in the toolbar or by using the key bindings. This makes it easier to quickly build new filters from existing ones. Changes to the preset filters are only applied and persisted to disk when the '''save filters''' button is pressed.
-
-To apply a saved preset filter in an events table, right-click on the table and select '''Apply preset filter...''' > ''filter name''.
-
-== Time Chart View ==
-
-[[Image:images/TimeChartView.png]]
-
-The Time Chart view allows the user to visualize every open trace in a common time chart. Each trace is display in its own row and ticks are display for every punctual event. As the user zooms using the mouse wheel or by right-clicking and dragging in the time scale, more detailed event data is computed from the traces.
-
-Time synchronization is enabled between the time chart view and other trace viewers such as the events table.
-
-Color settings defined in the Colors view can be used to change the tick color of events displayed in the Time Chart view.
-
-When a search is applied in the events table, the ticks corresponding to matching events in the Time Chart view are decorated with a marker below the tick.
-
-When a bookmark is applied in the events table, the ticks corresponding to the bookmarked event in the Time Chart view is decorated with a bookmark above the tick.
-
-When a filter is applied in the events table, the non-matching ticks are removed from the Time Chart view.
-
-The Time Chart only supports traces that are opened in an editor. The use of an editor is specified in the plug-in extension for that trace type, or is enabled by default for custom traces.
-
-== State System Explorer View ==
-
-The State System Explorer view allows the user to inspect the state interval values of every attribute of a state system at a particular time.
-
-The view shows a tree of currently selected traces and their registered state system IDs. For each state system the tree structure of attributes is displayed. The attribute name, quark, value, start and end time, and full attribute path are shown for each attribute.
-
-To modify the time of attributes shown in the view, select a different current time in other views that support time synchronization (e.g. event table, histogram view). When a time range is selected, this view uses the begin time.
-
-== Custom Parsers ==
-
-Custom parser wizards allow the user to define their own parsers for text or XML traces. The user defines how the input should be parsed into internal trace events and identifies the event fields that should be created and displayed. Traces created using a custom parser can be correlated with other built-in traces or traces added by plug-in extension.
-
-=== Creating a custom text parser ===
-
-The '''New Custom Text Parser''' wizard can be used to create a custom parser for text logs. It can be launched several ways:
-
-* Select '''File''' > '''New''' > '''Other...''' > '''Tracing''' > '''Custom Text Parser'''
-* Open the '''[[#Managing custom parsers|Manage Custom Parsers]]''' dialog, select the '''Text''' radio button and click the '''New...''' button
-
-[[Image:images/CustomTextParserInput.png]]
-
-Fill out the first wizard page with the following information:
-
-* '''Category:''' Enter a category name for the trace type.
-* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser.
-* '''Time Stamp format:''' Enter the date and time pattern that will be used to output the Time Stamp.<br>
-Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
-
-Click the '''Add next line''', '''Add child line''' or '''Remove line''' buttons to create a new line of input or delete it. For each line of input, enter the following information:
-
-* '''Regular expression:''' Enter a regular expression that should match the input line in the log, using capturing groups to extract the data.<br>
-Note: information about date and time patterns can be found here: [http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html]
-
-* '''Cardinality:''' Enter the minimum and maximum number of lines matching this line's regular expression that must be found in the log. At least the minimum number of lines must be found before the parser will consider the next line. Child lines will always be considered first.
-
-<u>Important note:</u> The custom parsers identify a log entry when the first line's regular expression matches (Root Line n). Each subsequent text line in the log is attempted to be matched against the regular expression of the parser's input lines in the order that they are defined (Line n.*). Only the first matching input line will be used to process the captured data to be stored in the log entry. When a text line matches a Root Line's regular expression, a new log entry is started.
-
-Click the '''Add group''' or '''Remove group''' buttons to define the data extracted from the capturing groups in the line's regular expression. For each group, enter the following information:
-
-* '''Name combo:''' Select a name for the extracted data:
-** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
-** '''Message''': Select this option to identify the main log entry's message. This is usually a group which could have text of greater length.
-** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box.
-
-* '''Action combo:''' Select the action to be performed on the extracted data:
-** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this group.
-** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this group.
-** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this group, using a | separator between matches.
-
-The '''Preview input''' text box can be used to enter any log data that will be processed against the defined custom parser. When the wizard is invoked from a selected log file resource, this input will be automatically filled with the file contents.
-
-The '''Preview:''' text field of each capturing group and of the Time Stamp will be filled from the parsed data of the first matching log entry.
-
-In the '''Preview input''' text box, the matching entries are highlighted with different colors:
-
-* <code><span style="background:#FFFF00"> Yellow </span></code> : indicates uncaptured text in a matching line.
-* <code><span style="background:#00FF00"> Green </span></code> : indicates a captured group in the matching line's regular expression for which a custom parser group is defined. This data will be stored by the custom parser.
-* <code><span style="background:#FF00FF"> Magenta</span></code> : indicates a captured group in the matching line's regular expression for which there is no custom parser group defined. This data will be lost.
-* <code> White </code> : indicates a non-matching line.
-
-The first line of a matching entry is highlighted with darker colors.
-
-By default only the first matching entry will be highlighted. To highlight all matching entries in the preview input data, click the '''Highlight All''' button. This might take a few seconds to process, depending on the input size.
-
-Click the '''Next >''' button to go to the second page of the wizard.
-
-[[Image:images/CustomTextParserOutput.png]]
-
-On this page, the list of default and custom data is shown, along with a preview of the custom parser log table output.
-
-The custom data output can be modified by the following options:
-
-* '''Visibility:''' Select or unselect the checkbox to display the custom data or hide it.
-
-* '''Column order:''' Click '''Move before''' or '''Move after''' to change the display order of custom data.
-
-The table at the bottom of the page shows a preview of the custom parser log table output according to the selected options, using the matching entries of the previous page's '''Preview input''' log data.
-
-Click the '''Finish''' button to close the wizard and save the custom parser.
-
-=== Creating a custom XML parser ===
-
-The '''New Custom XML Parser''' wizard can be used to create a custom parser for XML logs. It can be launched several ways:
-
-* Select '''File''' > '''New''' > '''Other...''' > '''Tracing''' > '''Custom XML Parser'''
-* Open the '''[[#Managing custom parsers|Manage Custom Parsers]]''' dialog, select the '''XML''' radio button and click the '''New...''' button
-
-[[Image:images/CustomXMLParserInput.png]]
-
-Fill out the first wizard page with the following information:
-
-* '''Category:''' Enter a category name for the trace type.
-* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser.
-* '''Time Stamp format:''' Enter the date and time pattern that will be used to output the Time Stamp.<br>
-
-Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
-
-Click the '''Add document element''' button to create a new document element and enter a name for the root-level document element of the XML file.
-
-Click the '''Add child''' button to create a new element of input to the document element or any other element. For each element, enter the following information:
-
-* '''Element name:''' Enter a name for the element that must match an element of the XML file.
-* '''Log entry:''' Select this checkbox to identify an element which represents a log entry. Each element with this name in the XML file will be parsed to a new log entry. At least one log entry element must be identified in the XML document. Log entry elements cannot be nested.
-* '''Name combo:''' Select a name for the extracted data:
-** '''Ignore''': Select this option to ignore the extracted element's data at this level. It is still possible to extract data from this element's child elements.
-** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
-** '''Message''': Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
-** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box. It does not have to match the element name.
-* '''Action combo:''' Select the action to be performed on the extracted data:
-** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this element.
-** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this element.
-** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this element, using a | separator between matches.
-
-Note: An element's extracted data 'value' is a parsed string representation of all its attributes, children elements and their own values. To extract more specific information from an element, ignore its data value and extract the data from one or many of its attributes and children elements.
-
-Click the '''Add attribute''' button to create a new attribute input from the document element or any other element. For each attribute, enter the following information:
-
-* '''Attribute name:''' Enter a name for the attribute that must match an attribute of this element in the XML file.
-* '''Name combo:''' Select a name for the extracted data:
-** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
-** '''Message''': Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
-** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box. It does not have to match the element name.
-* '''Action combo:''' Select the action to be performed on the extracted data:
-** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this element.
-** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this element.
-** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this element, using a | separator between matches.
-
-Note: A log entry can inherited input data from its parent elements if the data is extracted at a higher level.
-
-Click the '''Feeling lucky''' button to automatically and recursively create child elements and attributes for the current element, according to the XML element data found in the '''Preview input''' text box, if any.
-
-Click the '''Remove element''' or '''Remove attribute''' buttons to remove the extraction of this input data. Take note that all children elements and attributes are also removed.
-
-The '''Preview input''' text box can be used to enter any XML log data that will be processed against the defined custom parser. When the wizard is invoked from a selected log file resource, this input will be automatically filled with the file contents.
-
-The '''Preview:''' text field of each capturing element and attribute and of the Time Stamp will be filled from the parsed data of the first matching log entry. Also, when creating a new child element or attribute, its element or attribute name will be suggested if possible from the preview input data.
-
-Click the '''Next >''' button to go to the second page of the wizard.
-
-[[Image:images/CustomXMLParserOutput.png]]
-
-On this page, the list of default and custom data is shown, along with a preview of the custom parser log table output.
-
-The custom data output can be modified by the following options:
-
-* '''Visibility:''' Select or unselect the checkbox to display the custom data or hide it.
-* '''Column order:''' Click '''Move before''' or '''Move before''' to change the display order of custom data.
-
-The table at the bottom of the page shows a preview of the custom parser log table output according to the selected options, using the matching entries of the previous page's '''Preview input''' log data.
-
-Click the '''Finish''' button to close the wizard and save the custom parser.
-
-=== Managing custom parsers ===
-
-The '''Manage Custom Parsers''' dialog is used to manage the list of custom parsers used by the tool. To open the dialog:
-
-* Open the '''Project Explorer''' view.
-* Select '''Manage Custom Parsers...''' from the '''Traces''' folder context menu, or from a trace's '''Select Trace Type...''' context sub-menu.
-
-[[Image:images/ManageCustomParsers.png]]
-
-The ordered list of currently defined custom parsers for the selected type is displayed on the left side of the dialog.
-
-To change the type of custom parser to manage, select the '''Text''' or '''XML''' radio button.
-
-The following actions can be performed from this dialog:
-
-* New...
-
-Click the '''New...''' button to launch the '''New Custom Parser''' wizard.
-
-* Edit...
-
-Select a custom parser from the list and click the '''Edit...''' button to launch the '''Edit Custom Parser''' wizard.
-
-* Delete
-
-Select a custom parser from the list and click the '''Delete''' button to remove the custom parser.
-
-* Import...
-
-Click the '''Import...''' button and select a file from the opened file dialog to import all its custom parsers. If any parser conflicts with an existing built-in or custom trace type, the user will be prompted to skip or rename the imported parser.
-
-* Export...
-
-Select a custom parser from the list, click the '''Export...''' button and enter or select a file in the opened file dialog to export the custom parser. Note that if an existing file containing custom parsers is selected, the custom parser will be appended to the file.
-
-=== Opening a trace using a custom parser ===
-
-Once a custom parser has been created, any [[#Importing Traces to the Project|imported trace]] file can be opened and parsed using it.
-
-To do so:
-
-* Select a trace in the '''Project Explorer''' view
-* Right-click the trace and select '''Select Trace Type...''' > ''category name'' > ''parser name''
-* Double-click the trace or right-click it and select '''Open'''
-
-The trace will be opened in an editor showing the events table, and an entry will be added for it in the Time Chart view.
-
-= LTTng Tracer Control =
-
-The LTTng Tracer Control in Eclipse for the LTTng Tracer toolchain version v2.0 (or later) is done using SSH and requires an SSH server to be running on the remote host. For the SSH connection the SSH implementation of Remote Services is used. The functions to control the LTTng tracer (e.g. start and stop), either locally or remotely, are available from a dedicated Control View.
-
-In the following sections the LTTng 2.0 tracer control integration in Eclipse is described. Please refer to the LTTng 2.0 tracer control command line manual for more details and descriptions about all commands and their command line parameters [[#References | References]].
-
-== Control View ==
-To open the Control View, select '''Window->Show View->Other...->LTTng->Control View''.
-
-[[Image:images/LTTngControlView.png]]
-
-=== Creating a New Connection to a Remote Host ===
-
-To connect to a remote host, select the '''New Connection''' button in the Control View.
-
-[[Image:images/LTTngControlViewConnect.png]]
-
-A new dialog is opened for selecting a remote connection. You can also edit or define a remote connection from here.
-
-[[Image:images/LTTng2NewConnection.png]]
-
-To define a new remote host using the default SSH service, select '''Buit-in SSH''' and then select '''Create...'''. This will start the standard '''New Connection''' wizard provided by the Remote Services plugin. Similar, to edit the definition of a remote connection, select '''Edit...''' and use the '''Edit Connection''' wizard provided by the SSH service. In case you have installed an additional adapter for the Remote Services, you can choose to define a remote connection based on this adapter.
-
-[[Image:images/LTTng2NewRemoteConnection.png]]
-
-To use an existing connection definition, select the relevant entry in the tree and then select '''Ok'''.
-
-[[Image:images/LTTng2SelectConnection.png]]
-
-A new display will show for providing the user name and password. This display only opens if no password had been saved before. Enter user name and password in the '''Password Required''' dialog box and select '''Ok'''.
-
-[[Image:images/LTTng2EnterPassword.png]]
-
-After pressing '''Ok''' the SSH connection will be established and after successful login the Control View implementation retrieves the LTTng Tracer Control information. This information will be displayed in the Control View in form of a tree structure.
-
-[[Image:images/LTTng2ControlViewFilled.png]]
-
-The top level tree node is the representation of the remote connection (host). The connection name of the connection will be displayed. Depending on the connection state different icons are displayed. If the node is '''CONNECTED''' the icon is shown [[Image:images/Target_connected.gif]], otherwise (states '''CONNECTING''', '''DISCONNNECTING''' or '''DISCONNECTED''' the icon is [[Image:images/Target_disconnected.gif]].
-
-Under the host level two folder groups are located. The first one is the '''Provider''' group. The second one is the '''Sessions''' group.
-
-Under the '''Provider''' group all trace providers are displayed. Trace providers are '''Kernel''' and any user space application that supports UST tracing. Under each provider a corresponding list of events are displayed.
-
-Under the '''Sessions''' group all current sessions will be shown. The level under the sessions show the configured domains. Currently the LTTng 2.0 Tracer Toolchan supports domain '''Kernel''' and '''UST global'''. Under each domain the configured channels will be displayed. The last level is under the channels where the configured events are displayed.
-
-Each session can be '''ACTIVE''' or '''INACTIVE'''. Active means that tracing has been started, inactive means that the tracing has been stopped. Depending on the state of a session a different icon is displayed. The icon for an active session is [[Image:images/Session_active.gif]]. The icon for an inactive session is [[Image:images/Session_inactive.gif]].
-
-Each channel can be '''ENABLED''' or '''DISABLED'''. An enabled channel means that all configured events of that channel will be traced and a disabled channel won't trace any of its configured events. Different icons are displayed depending on the state of the channel. The icon for an enabled channel is [[Image:images/Channel.gif]] and the icon for a disabled channel is [[Image:images/Channel_disabled.gif]].
-
-Events within a channel can be in state '''ENABLED''' or '''DISABLED'''. Enabled events are stored in the trace when passed during program execution. Disabled events on the other hand won't be traced. Depending on the state of the event the icons for the event is different. An enabled event has the icon [[Image:images/Event_enabled.gif]] and a disabled event the icon [[Image:images/Event_disabled.gif]].
-
-=== Disconnecting from a Remote Host ===
-
-To disconnect from a remote host, select the host in the Control View and press the '''Disconnect''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Disconnect''' button.
-
-[[Image:images/LTTng2ControlViewDisconnect.png]]
-
-=== Connecting to a Remote Host ===
-
-To connect to a remote host, select the host in the Control View and press the '''Connect''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Connect''' button. This will start the connection process as discribed in [[#Creating a New Connection to a Remote Host | Creating a New Connection to a Remote Host]].
-
-[[Image:images/LTTng2ControlViewConnect.png]]
-
-=== Deleting to a Remote Host Connection ===
-
-To delete a remote host connection, select the host in the Control View and press the '''Delete''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Delete''' button. For that command to be active the connection state has to be '''DISCONNECTED''' and the trace has to be closed.
-
-[[Image:images/LTTng2ControlViewDelete.png]]
-
-=== Creating a Tracing Session ===
-To create a tracing session, select the tree node '''Sessions''' and press the right mouse button. Then select the '''Create Session...''' button of the context-sensitive menu.
-
-[[Image:images/LTTng2CreateSessionAction.png]]
-
-A dialog box will open for entering information about the session to be created.
-
-[[Image:images/LTTng2CreateSessionDialog.png]]
-
-Fill in the '''Session Name''' and optionally the '''Session Path''' and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
-
-=== Creating a Tracing Session With Advanced Options ===
-LTTng Tools version v2.1.0 introduces the possibility to configure the trace output location at session creation time. The trace can be stored in the (tracer) local file system or can be transferred over the network.
-
-To create a tracing session and configure the trace output, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]]. A dialog box will open for entering information about the session to be created.
-
-[[Image:images/LTTng2CreateSessionDialog_Advanced.png]]
-
-The button '''Advanced >>>''' will only show if the remote host has LTTng Tools v2.1.0 installed. To configure the trace output select the '''Advanced >>>''' button. The Dialog box will be shown new fields to configure the trace output location.
-
-[[Image:images/LTTng2CreateSessionDialog_TracePath.png]]
-
-By default, the button '''Use same protocol and address for data and control''' is selected which allows to configure the same '''Protocol''' and '''Address''' for both data URL and control URL.
-
-If button '''Use same protocol and address for data and control''' is selected the '''Protocol''' can be '''net''' for the default network protocol which is TCP (IPv4), '''net6''' for the default network protocol which is TCP (IPv6) and '''file''' for the local file system. For '''net''' and '''net6''' the port can be configured. Enter a value in '''Port''' for data and control URL or keep them empty for the default port to be used. Using '''file''' as protocol no port can be configured and the text fields are disabled.
-
-If button '''Use same protocol and address for data and control''' is not selected the '''Protocol''' can be '''net''' for the default network protocol which is TCP (IPv4), '''net6''' for the default network protocol which is TCP (IPv6), '''tcp''' for the network protocol TCP (IPv4) and '''tcp6''' for the network protocol TCP (IPv6). Note that for '''net''' and '''net6''' always the default port is used and hence the port text fields are disabled. To configure non-default ports use '''tcp''' or '''tcp6'''.
-
-The text field '''Trace Path''' allows for specifying the path relative to the location defined by the '''relayd''' or relative to the location specified by the '''Address''' when using protocol '''file'''. For more information about the '''relayd''' see '''LTTng relayd User Manual''' in chapter [[#References | References]].
-
-To create a session with advanced options, fill in the relevant parameters and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
-
-=== Creating a Snapshot Tracing Session ===
-LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After starting tracing the trace events are not stored on disk or over the network. They are only transfered to disk or over the network when the user records a snapshot. To create such a snapshot session, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]].
-
-[[Image:images/LTTng2CreateSessionDialog_Snapshot.png]]
-
-Fill in all necessary information, select the radio button for '''Snapshot Mode''' and press '''Ok'''. By default, the location for the snapshot output will be on the host where the host is located.
-
-Refer to chapter [[#Recording a Snapshot | Recording a Snapshot]] for how to create a snapshot.
-
-=== Creating a Live Tracing Session ====
-LTTng Tools version v2.4.0 introduces the possibility to create live tracing sessions. The live mode allows you to stream the trace and view it while it's being recorded. To create such a live session, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]].
-
-[[Image:images/LTTng2CreateSessionDialog_Live.png]]
-
-In the advanced options, it is possible to set the '''Live Delay'''. The '''Live Delay''' is the delay in micro seconds before the data is flushed and streamed.
-
-[[Image:images/LTTng2CreateSessionDialog_Live_Advanced.png]]
-
-Fill in all necessary information, select the radio button for '''Live Mode''' and press '''Ok'''.
-
-=== Enabling Channels - General ===
-
-Enabling channels can be done using a session tree node when the domain hasn't be created in the session or, alternatively on a domain tree node of a session in case the domain is already available.
-
-=== Enabling Channels On Session Level ===
-
-To enable a channel, select the tree node of the relevant session and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
-
-[[Image:images/LTTng2CreateChannelAction.png]]
-
-A dialog box will open for entering information about the channel to be created.
-
-[[Image:images/LTTng2CreateChannelDialog.png]]
-
-By default the domain '''Kernel''' is selected. To create a UST channel, select '''UST''' under the domain section. The label <Default> in any text box indicates that the default value of the tracer will be configured. To initialize the dialog box press button '''Default'''.
-
-If required update the following channel information and then press '''Ok'''.
-
-* '''Channel Name''': The name of the channel.
-* '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
-* '''Number of Sub Buffers''': The number of sub-buffers of the channel.
-* '''Switch Timer Interval''': The switch timer interval.
-* '''Read Timer Interval''': The read timer interval.
-* '''Discard Mode''': '''Overwrite''' events in buffer or '''Discard''' new events when buffer is full.
-
-Upon successful operation, the requested domain will be created under the session tree node as well as the requested channel will be added under the domain. The channel will be '''ENABLED'''.
-
-=== Configuring Trace File Rotation ===
-
-Since LTTng Tools v2.2.0 it is possible to set the maximum size of trace files and the maximum number of them. These options are located in the same dialog box that is used for enabling channels.
-
-[[Image:images/LTTng2CreateChannelDialogFileRotation.png]]
-
-* '''Maximum size of trace files''': The maximum size of trace files
-* '''Maximum number of trace files''': The maximum number of trace files
-
-=== Configuring per UID and per PID Buffers (UST only) ===
-
-Since LTTng Tools v2.2.0 it is possible to configure the type of buffers for '''UST''' application. It is now possible to choose between per '''UID''' buffers (per user ID) and per '''PID''' buffers (per process ID) using the dialog box for enabling channels.
-
-[[Image:images/LTTng2CreateChannelDialogPerUIDBuffers.png]]
-
-* '''Per PID buffers''': To activate the per PID buffers option for UST channels
-* '''Per UID buffers''': To activate the per UID buffers option for UST channels
-
-If no buffer type is selected then the default value of the tracer will be configured.
-
-Note that '''Global shared buffers''' is only for kernel channel and is pre-selected when '''Kernel''' is selected in the dalog box.
-
-=== Configuring Periodical Flush for metadata Channel ===
-
-Since LTTng Tools v2.2.0 it is possible to configure periodical flush for the metadata channel. To set this, use the checkbox '''Configure metadata channel''' then fill the switch timer interval.
-
-[[Image:images/LTTng2CreateChannelDialogMetadataFlush.png]]
-
-=== Enabling Channels On Domain Level ===
-
-Once a domain is available, channels can be enabled directly using the domain. To enable a channel under an existing domain, select the tree node of the relevant domain and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
-
-[[Image:images/LTTng2CreateChannelOnDomainAction.png]]
-
-The dialog box for enabling channel will open for entering information about the channel to be created. Note that the domain is pre-selected and cannot be changed. Fill the relevant information and press '''Ok'''.
-
-=== Enabling and Disabling Channels ===
-
-To disable one or more enabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the '''Disable Channel''' menu item of the context-sensitive menu.
-
-[[Image:images/LTTng2DisableChannelAction.png]]
-
-Upon successful operation, the selected channels will be '''DISABLED''' and the icons for the channels will be updated.
-
-To enable one or more disabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the '''Enable Channel''' menu item of the context-sensitive menu.
-
-[[Image:images/LTTng2EnableChannelAction.png]]
-
-Upon successful operation, the selected channels will be '''ENABLED''' and the icons for the channels will be updated.
-
-=== Enabling Events - General ===
-
-Enabling events can be done using different levels in the tree node. It can be done on the session, domain level and channel level. For the case of session or domain, i.e. when no specific channels is assigned then enabling of events is done on the default channel with the name '''channel0''' which created, if not already exists, by the LTTng tracer control on the server side.
-
-=== Enabling Kernel Events On Session Level ===
-
-To enable events, select the tree node of the relevant session and press the right mouse button. Then select the '''Enable Event (default channel)...''' button of the context-sensitive menu.
-
-[[Image:images/LTTng2EventOnSessionAction.png]]
-
-A dialog box will open for entering information about events to be enabled.
-
-[[Image:images/LTTng2EventOnSessionDialog.png]]
-
-By default the domain '''Kernel''' is selected and the kernel specific data sections are created. From this dialog box kernel '''Tracepoint''' events, '''System calls (Syscall)''', a '''Dynamic Probe''' or a '''Dynamic Function entry/return''' probe can be enabled. Note that events of one of these types at a time can be enabled.
-
-To enable '''Tracepoint''' events, first select the corresponding '''Select''' button, then select either all tracepoins (select '''All''') or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press '''Ok'''.
-
-[[Image:images/LTTng2TracepointEventsDialog.png]]
-
-Upon successful operation, the domain '''Kernel''' will be created in the tree (if neccessary), the default channel with name "channel0" will be added under the domain (if necessary) as well as all requested events of type '''TRACEPOINT''' under the channel. The channel and events will be '''ENABLED'''.
-
-[[Image:images/LTTng2EnabledKernelTracepoints.png]]
-
-To enable all '''Syscalls''', select the corresponding '''Select''' button and press '''Ok'''.
-
-[[Image:images/LTTng2SyscallsDialog.png]]
-
-Upon successful operation, the event with the name '''syscalls''' and event type '''SYSCALL''' will be added under the default channel (channel0). If necessary the domain '''Kernel''' and the channel '''channel0''' will be created.
-
-[[Image:images/LTTng2EnabledKernelSyscalls.png]]
-
-To enable a '''Dynamic Probe''' event, select the corresponding '''Select''' button, fill the '''Event Name''' and '''Probe''' fields and press '''Ok'''. Note that the probe can be an address, symbol or a symbol+offset where the address and offset can be octal (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...).
-
-[[Image:images/LTTng2ProbeEventDialog.png]]
-
-Upon successful operation, the dynamic probe event with the given name and event type '''PROBE''' will be added under the default channel (channel0). If necessary the domain '''Kernel''' and the channel '''channel0''' will be created.
-
-[[Image:images/LTTng2EnabledKernelProbeEvent.png]]
-
-To enable a '''Dynamic Function entry/return Probe''' event, select the corresponding '''Select''' button, fill the '''Event Name''' and '''Function''' fields and press '''Ok'''. Note that the funtion probe can be an address, symbol or a symbol+offset where the address and offset can be octal (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...).
-
-[[Image:images/LTTng2FunctionEventDialog.png]]
-
-Upon successful operation, the dynamic function probe event with the given name and event type '''PROBE''' will be added under the default channel (channel0). If necessary the domain '''Kernel''' and the channel '''channel0''' will be created.
-
-[[Image:images/LTTng2EnabledFunctionProbeEvent.png]]
-
-=== Enabling UST Events On Session Level ===
-
-For enabling UST events, first open the enable events dialog as described in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]] and select domain '''UST'''.
-
-To enable '''Tracepoint''' events, first select the corresponding '''Select''' button, then select either all tracepoins (select '''All''') or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press '''Ok'''.
-
-[[Image:images/LTTng2UstTracepointEventsDialog.png]]
-
-Upon successful operation, the domain '''UST global''' will be created in the tree (if neccessary), the default channel with name "channel0" will be added under the domain (if necessary) as well as all requested events under the channel. The channel and events will be '''ENABLED'''. Note that for the case that '''All''' tracepoints were selected the wildcard '''*''' is used which will be shown in the Control View as below.
-
-[[Image:images/LTTng2EnabledAllUstTracepoints.png]]
-
-For UST it is possible to enable '''Tracepoint''' events using a wildcard. To enable '''Tracepoint''' events with a wildcard, select first the corresponding '''Select''' button, fill the '''Wildcard''' field and press '''Ok'''.
-
-[[Image:images/LTTng2UstWildcardEventsDialog.png]]
-
-Upon successful operation, the event with the given wildcard and event type '''TRACEPOINT''' will be added under the default channel (channel0). If necessary the domain '''UST global''' and the channel '''channel0''' will be created.
-
-[[Image:images/LTTng2EnabledUstWildcardEvents.png]]
-
-For UST it is possible to enable '''Tracepoint''' events using log levels. To enable '''Tracepoint''' events using log levels, select first the corresponding '''Select''' button, select a log level from the drop down menu, fill in the relevant information (see below) and press '''Ok'''.
-
-* '''Event Name''': Name to display
-* '''loglevel''': To specify if a range of log levels (0 to selected log level) shall be configured
-* '''loglevel-only''': To specify that only the specified log level shall be configured
-
-[[Image:images/LTTng2UstLoglevelEventsDialog.png]]
-
-Upon successful operation, the event with the given event name and event type '''TRACEPOINT''' will be added under the default channel (channel0). If necessary the domain '''UST global''' and the channel '''channel0''' will be created.
-
-[[Image:images/LTTng2EnabledUstLoglevelEvents.png]]
-
-=== Enabling Events On Domain Level ===
-
-Kernel events can also be enabled on the domain level. For that select the relevant domain tree node, click the right mouse button and the select '''Enable Event (default channel)...'''. A new dialog box will open for providing information about the events to be enabled. Depending on the domain, '''Kernel''' or '''UST global''', the domain specifc fields are shown and the domain selector is preselected and read-only.
-
-[[Image:images/LTTng2EventOnDomainAction.png]]
-
-To enable events for domain '''Kernel''' follow the instructions in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]], for domain '''UST global''', see section [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]].
-The events will be add to the default channel '''channel0'''. This channel will be created by on the server side if neccessary.
-
-=== Enabling Events On Channel Level ===
-
-Kernel events can also be enabled on the channel level. If necessary, create a channel as described in sections [[#Enabling Channels On Session Level | Enabling Channels On Session Level]] or [[#Enabling Channels On Domain Level | Enabling Channels On Domain Level]].
-
-Then select the relevant channel tree node, click the right mouse button and the select '''Enable Event...'''. A new dialog box will open for providing information about the events to be enabled. Depending on the domain, '''Kernel''' or '''UST global''', the domain specifc fields are shown and the domain selector is preselected and read-only.
-
-[[Image:images/LTTng2EventOnChannelAction.png]]
-
-To enable events for domain '''Kernel''' follow the instructions in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]], for domain '''UST global''' [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]].
-
-When enabling events on the channel level, the events will be add to the selected channel.
-
-=== Enabling and Disabling Events ===
-
-To disable one or more enabled events, select the tree nodes of the relevant events and click the right mouse button. Then select '''Disable Event''' menu item in the context-sensitive menu.
-
-[[Image:images/LTTng2DisableEventAction.png]]
-
-Upon successful operation, the selected events will be '''DISABLED''' and the icons for these events will be updated.
-
-To enable one or more disabled events, select the tree nodes of the relevant events and press the right mouse button. Then select the '''Enable Event''' menu item of the context-sensitive menu.
-
-[[Image:images/LTTng2EnableEventAction.png]]
-
-Upon successful operation, the selected events will be '''ENABLED''' and the icons for these events will be updated.
-
-'''Note''': There is currently a limitation for kernel event of type '''SYSCALL'''. This kernel event can not be disabled. An error will appear when trying to disable this type of event. A work-around for that is to have the syscall event in a separate channel and disable the channel instead of the event.
-
-=== Enabling Tracepoint Events From Provider ===
-
-It is possible to enable events of type '''Tracepoint''' directly from the providers and assign the enabled event to a session and channel. Before doing that a session has to be created as described in section [[#Creating a Tracing Session | Creating a Tracing Session]]. Also, if other than default channel '''channel0''' is required, create a channel as described in sections [[#Enabling Channels On Session Level | Enabling Channels On Session Level]] or [[#Enabling Channels On Domain Level | Enabling Channels On Domain Level]].
-
-To assign tracepoint events to a session and channel, select the events to be enabled under the provider (e.g. provider '''Kernel'''), click right mouse button and then select '''Enable Event...''' menu item from the context sensitive menu.
-
-[[Image:images/LTTng2AssignEventAction.png]]
-
-A new display will open for defining the session and channel.
-
-[[Image:images/LTTng2AssignEventDialog.png]]
-
-Select a session from the '''Session List''' drop-down menu, a channel from the '''Channel List''' drop-down menu and the press '''Ok'''. Upon successful operation, the selected events will be added to the selected session and channel of the domain that the selected provider belongs to. In case that there was no channel available, the domain and the default channel '''channel0''' will be created for corresponding session. The newly added events will be '''ENABLED'''.
-
-[[Image:images/LTTng2AssignedEvents.png]]
-
-=== Configuring Filter Expression On UST Event Fields ===
-
-Since LTTng Tools v2.1.0 it is possible to configure a filter expression on UST event fields. To configure a filter expression on UST event fields, open the enable event dialog as described in chapters [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]], [[#Enabling Events On Domain Level | Enabling Events On Domain Level]] or [[#Enabling Events On Channel Level | Enabling Events On Channel Level]], select UST if needed, select the relevant '''Tracepoint''' event(s) and enter the filter expression in the '''Filter Expression''' text field.
-
-[[Image:images/LTTng2EnableEventWithFilter.png]]
-
-Alternatively, open the dialog box for assigning events to a session and channel described in [[#Enabling Tracepoint Events From Provider | Enabling Tracepoint Events From Provider]] (for UST providers) and enter the filter expression in the '''Filter Expression''' text field.
-
-[[Image:images/LTTng2AssignEventDialogWithFilter.png]]
-
-For the syntax of the filter expression refer to the '''LTTng Tracer Control Command Line Tool User Manual''' of chapter [[#References |References]].
-
-=== Adding Contexts to Channels and Events of a Domain ===
-
-It is possible to add contexts to channels and events. Adding contexts on channels and events from the domain level, will enable the specified contexts to all channels of the domain and all their events. To add contexts on the domain level, select a domain, click right mouse button on a domain tree node (e.g. provider '''Kernel''') and select the menu item '''Add Context...''' from the context-sensitive menu.
-
-[[Image:images/LTTng2AddContextOnDomainAction.png]]
-
-A new display will open for selecting one or more contexts to add.
-
-[[Image:images/LTTng2AddContextDialog.png]]
-
-The tree shows all available context that can be added. Select one or more context and the press '''Ok'''. Upon successful operation, the selected context will be added to all channels and their events of the selected domain.
-
-'''Note''': The LTTng UST tracer only supports contexts '''procname''', '''pthread_id''', '''vpid''' '''vtid'''. Adding any other contexts in the UST domina will fail.
-
-=== Adding Contexts to All Events of a Channel ===
-
-Adding contexts on channels and events from the channel level, will enable the specified contexts to all events of the selected channel. To add contexts on the channel level, select a channel, click right mouse button on a channel tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
-
-[[Image:images/LTTng2AddContextOnChannelAction.png]]
-
-A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter [[#Adding Contexts to Channels and Events of a Domain | Adding Contexts to Channels and Events of a Domain]]. Upon successful operation, the selected context will be added to all channels and their events of the selected domain. '''Note''' that the LTTng 2.0 tracer control on the remote host doesn't provide a way to retrieve added contexts. Hence it's not possible to display the context information in the GUI.
-
-=== Adding Contexts to an Event of a Specific Channel ===
-
-Adding contexts to an event of a channel is only available in LTTng Tools versions v2.0.0-2.1.x. The menu option won't be visible for LTTng Tools version v2.2.0 or later. To add contexts on an event select an event of a channel, click right mouse button on the corresponding event tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
-
-[[Image:images/LTTng2AddContextToEventsAction.png]]
-
-A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter [[#Adding Contexts to Channels and Events of a Domain | Adding Contexts to Channels and Events of a Domain]]. Upon successful operation, the selected context will be added to the selected event.
-
-=== Start Tracing ===
-
-To start tracing, select one or more sessions to start in the Control View and press the '''Start''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Start''' menu item.
-
-[[Image:images/LTTng2StartTracingAction.png]]
-
-Upon successful operation, the tracing session will be '''ACTIVE''' and the icon of the session will be updated.
-
-=== Recording a Snapshot ===
-
-LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After creating a snapshot session (see [[#Creating a Snapshot Tracing Session | Creating a Snapshot Tracing Session]]) and starting tracing (see [[#Start Tracing | Start Tracing]]) it possible to record snapshots. To record a snapshot select one or more sessions and press the '''Record Snapshot''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Recored Snapshot''' menu item.
-
-[[Image:images/LTTng2RecordSnapshotAction.png]]
-
-This action can be executed many times. It is possible to import the recorded snpshots to a tracing project. The trace session might be '''ACTIVE''' or '''INACTIVE''' for that. Refer to section [[#Importing Session Traces to a Tracing Project | Importing Session Traces to a Tracing Project]] on how to import a trace to a tracing project.
-
-=== Stop Tracing ===
-
-To stop tracing, select one or more sessions to stop in the Control View and press the '''Stop''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Stop''' menu item.
-
-[[Image:images/LTTng2StopTracingAction.png]]
-
-Upon successful operation, the tracing session will be '''INACTIVE''' and the icon of the session will be updated.
-
-=== Destroying a Tracing Session ===
-
-To destroy a tracing session, select one or more sessions to destroy in the Control View and press the '''Destroy''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Destroy...''' menu item. Note that the session has to be '''INACTIVE''' for this operation.
-
-[[Image:images/LTTng2DestroySessionAction.png]]
-
-A confirmation dialog box will open. Click on '''Ok''' to destroy the session otherwise click on '''Cancel'''.
-
-[[Image:images/LTTng2DestroyConfirmationDialog.png]]
-
-Upon successful operation, the tracing session will be destroyed and removed from the tree.
-
-=== Refreshing the Node Information ===
-
-To refresh the remote host information, select any node in the tree of the Control View and press the '''Refresh''' button. Alternatively, click the right mouse button on any tree node. A context-sensitive menu will show. Then select the '''Refresh''' menu item.
-
-[[Image:images/LTTng2RefreshAction.png]]
-
-Upon successful operation, the tree in the Control View will be refreshed with the remote host configuration.
-
-=== Quantifing LTTng overhead (Calibrate) ===
-
-The LTTng calibrate command can be used to find out the combined average overhead of the LTTng tracer and the instrumentation mechanisms used. For now, the only calibration implemented is that of the kernel function
-instrumentation (kretprobes). To run the calibrate command, select the a domain (e.g. '''Kernel'''), click the right mouse button on the domain tree node. A context-sensitive menu will show. Select the '''Calibrate''' menu item.
-
-[[Image:images/LTTng2CalibrateAction.png]]
-
-Upon successful operation, the calibrate command is executed and relevant information is stored in the trace. Note: that the trace has to be active so that to command as any effect.
-
-=== Importing Session Traces to a Tracing Project ===
-
-To import traces from a tracing session, select the relevant session and click on the '''Import''' Button. Alternatively, click the right mouse button on the session tree node and select the menu item '''Import...''' from the context-sensitive menu.
-
-[[Image:images/LTTng2ImportAction.png]]
-
-A new display will open for selecting the traces to import.
-
-[[Image:images/LTTng2ImportDialog.png]]
-
-By default all traces are selected. A default project with the name '''Remote''' is selected which will be created if necessary. Update the list of traces to be imported, if necessary, by selecting and deselecting the relevant traces in the tree viewer. Use buttons '''Select All''' or '''Deselect All''' to select or deselect all traces. Also if needed, change the tracing project from the '''Available Projects''' combo box. Select the Overwrite button ('''Overwrite existing trace without warning''') if required. Then press button '''Ok'''. Upon successful import operation the selected traces will be stored in the '''Traces''' directory of the specified tracing project. The session directory structure as well as the trace names will be preserved in the destination tracing project. For '''Kernel''' traces the trace type '''LTTng Kernel Trace''' and for '''UST''' traces the trace type '''LTTng UST Trace''' will be set. From the '''Project Explorer''' view, the trace can be analyzed further.
-
-'''Note''': If the overwrite button ('''Overwrite existing trace without warning''') was not selected and a trace with the same name of a trace to be imported already exists in the destination directory of the project, then a new confirmation dialog box will open.
-
-[[Image:images/LTTng2ImportOverwriteConfirmationDialog.png]]
-
-To Overwrite select the '''Overwrite''' Button and press '''Ok'''.
-
-If the existing trace should not be overwritten select, then select the '''Rename''' option of the confirmation dialog box above, enter a new name and then press '''Ok'''.
-
-[[Image:images/LTTng2ImportRenameDialog.png]]
-
-=== Importing Network Traces to a Tracing Project ===
-
-Since LTTng Tools v2.1.0 it is possible to store traces over the network. To import network traces, execute the '''Import''' action as described in chapter [[#Importing Session Traces to a Tracing Project | Importing Session Traces to a Tracing Project]]. For network traces the '''Import Trace Wizard''' will be displayed. Follow the instructions in chapter [[#Importing | Importing]] to import the network traces of the current session.
-
-== Properties View ==
-
-The Control View provides property information of selected tree component. Depending on the selected tree component different properties are displayed in the property view. For example, when selecting the node level the property view will be filled as followed:
-
-[[Image:images/LTTng2PropertyView.png]]
-
-'''List of properties''':
-
-* '''Host''' Properties
-** '''Connection Name''': The alias name to be displayed in the Control View.
-** '''Host Name''': The IP address or DNS name of the remote system.
-** '''State''': The state of the connection ('''CONNECTED''', '''CONNECTING''', '''DISCONNNECTING''' or '''DISCONNECTED''').
-* '''Kernel Provider''' Properties
-** '''Provider Name''': The name of the provider.
-* '''UST Provider''' Properties
-** '''Provider Name''': The name of the provider.
-** '''Process ID''': The process ID of the provider.
-* '''Event''' Properties (Provider)
-** '''Event Name''': The name of the event.
-** '''Event Type''': The event type ('''TRACEPOINT''' only).
-** '''Fields''': Shows a list of fields defined for the selected event. (UST only, since support for LTTng Tools v2.1.0)
-** '''Log Level''': The log level of the event.
-* '''Session''' Properties
-** '''Session Name''': The name of the Session.
-** '''Session Path''': The path on the remote host where the traces will be stored. (Not shown for snapshot sessions).
-** '''State''': The state of the session ('''ACTIVE''' or '''INACTIVE''')
-** '''Snapshot ID''': The snapshot ID. (Only shown for snapshot sessions).
-** '''Snapshot Name''': The name of the snapshot output configuration. (Only shown for snapshot sessions).
-** '''Snapshot Path''': The path where the snapshot session is located. (Only shown for snapshot sessions).
-* '''Domain''' Properties
-** '''Domain Name''': The name of the domain.
-** '''Buffer Type''': The buffer type of the domain.
-* '''Channel''' Properties
-** '''Channel Name''': The name of the channel.
-** '''Number of Sub Buffers''': The number of sub-buffers of the channel.
-** '''Output type''': The output type for the trace (e.g. ''splice()'' or ''mmap()'')
-** '''Overwrite Mode''': The channel overwrite mode ('''true''' for overwrite mode, '''false''' for discard)
-** '''Read Timer Interval''': The read timer interval.
-** '''State''': The channel state ('''ENABLED''' or '''DISABLED''')
-** '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
-** '''Switch Timer Interval''': The switch timer interval.
-* '''Event''' Properties (Channel)
-** '''Event Name''': The name of the event.
-** '''Event Type''': The event type ('''TRACEPOINT''', '''SYSCALL''' or '''PROBE''').
-** '''Log Level''': The log level of the event. (For LTTng Tools v2.4.0 or later, '''<=''' prior the log level name will indicate a range of log levels and '''==''' a single log level.)
-** '''State''': The Event state ('''ENABLED''' or '''DISABLED''')
-** '''Filter''': Shows '''with filter''' if a filter expression is configured else property '''Filter''' is omitted. (since support for LTTng Tools v2.1.0)
-
-== LTTng Tracer Control Preferences ==
-
-Serveral LTTng 2.0 tracer control preferences exists which can be configured. To configure these preferences, select '''Window->Preferences''' from the top level menu. The preference display will open. Then select '''Tracing->LTTng Tracer Control Preferences'''. This preferences page allows the user to specify the tracing group of the user and to specify the command execution timeout as well as it allows the user to configure the logging of LTTng 2.0 tracer control commands and results to a file.
-
-[[Image:images/LTTng2Preferences.png]]
-
-To change the tracing group of the user which will be specified on each command line, enter the new group name in the '''Tracing Group''' text field and click button '''OK'''. The default tracing group is '''tracing''' and can be restored by pressing the '''Restore Defaults''' button.
-
-[[Image:images/LTTng2PreferencesGroup.png]]
-
-To configure logging of trace control commands and the corresponding command result to a file, selected the button '''Logging'''. To append to an existing log file, select the '''Append''' button. Deselect the '''Append''' button to overwrite any existing log file. It's possible to specify a verbose level. There are 3 levels with inceasing verbosity from '''Level 1''' to '''Level 3'''. To change the verbosity level, select the relevant level or select '''None'''. If '''None''' is selected only commands and command results are logged. Then press on button '''OK'''. The log file will be stored in the users home directory with the name ''lttng_tracer_control.log''. The name and location cannot be changed. To reset to default preferences, click on the button '''Restore Defaults'''.
-
-[[Image:images/LTTng2PreferencesLogging.png]]
-
-To configure the LTTng command execution timeout, enter a timeout value into the text field '''Command Timeout (in seconds)''' and press on button '''OK'''. To reset to the default value of 15 seconds, click on the button '''Restore Defaults'''.
-
-[[Image:images/LTTng2PreferencesTimeout.png]]
-
-= LTTng Kernel Analysis =
-
-Historically, LTTng was developped to trace the Linux kernel and, over time, a number of kernel-oriented analysis views were developped and organized in a perspective.
-
-This section presents a description of the LTTng Kernel Perspective.
-
-== LTTng Kernel Perspective ==
-
-The '''LTTng Kernel''' perspective is built upon the [[#Tracing_Perspective | Tracing Perspective]], re-organizes them slightly and adds the following views:
-
-* [[#Control_Flow_View | Control Flow View]] - to visualize processes state transitions
-* [[#Resources_View | Resources View]] - to visualize system resources state transitions
-* [[#LTTng_Tracer_Control | LTTng Tracer Control]] - to configure LTTng tracing sessions remotely
-
-[[Image:images/LTTngKernelPerspective.png]]
-
-
-The perspective can be opened from the Eclipse Open Perspective dialog ('''Window > Open Perspective... > Other''').
-
-
-[[Image:images/OpenLTTngKernelPerspective.png]]
-
-== Control Flow View ==
-
-The '''''Control Flow''''' view is a LTTng-specific view that shows per-process events graphically. The LTTng Kernel analysis is executed the first time a LTTng Kernel is opened. After opening the trace, the element '''Control Flow''' is added under the '''LTTng Kernel Analysis''' tree element in the Project Explorer. To open the view, double-click the '''Control Flow''' tree element.
-
-[[Image:images/Cfv_show_view.png]]
-
-Alternatively, select ''Control Flow'' under ''LTTng'' within the ''Show View'' window ('''Window''' -> '''Show View''' -> '''Other...'''):
-
-You should get something like this:
-
-[[Image:images/Cfv_global.png]]
-
-The view is divided into the following important sections: '''process tree and information''', '''control flow''' and the '''toolbar'''.
-
-The following sections provide detailed information for each part of the Control Flow View.
-
-=== Process tree and information ===
-
-Processes are organized as a tree within this view. This way, child and parent processes are easy to identify.
-
-[[Image:images/Cfv_process_tree.png]]
-
-The layout is based on the states computed from the trace events.
-
-A given process may be shown at different places within the tree since the nodes are '''unique (TID, birth time) couples'''. This means that if process B of parent A dies, you'll still see it in the tree. If process A forks process B again, it will be shown as a different node since it won't have the same birth time (and probably not the same TID). This has the advantage that the tree, once loaded, never changes: horizontal scrolling within the [[#Control flow|control flow]] remains possible.
-
-The TID column shows the process node's '''thread ID''' and the PTID column shows its '''parent thread ID''' (nothing is shown if the process has no parent).
-
-=== Control flow ===
-
-This part of the Control Flow View is probably the most interesting one. Using the mouse, you can navigate through the trace (go left, right) and zoom on a specific region to inspect its details.
-
-The colored bars you see represent '''states''' for the associated process node. When a process state changes in time, so does the color. For state '''SYSCALL''' the name of the system call is displayed in the state bar. States colors legend is available through a [[#Toolbar|toolbar button]]:
-
-[[Image:images/Cfv_legend.png]]
-
-This dark yellow is what you'll see most of the time since scheduling puts processes on hold while others run.
-
-The vertical blue line with T1 above it is the '''current selection indicator'''. When a time range is selected, the region between the begin and end time of the selection will be shaded and two lines with T1 and T2 above will be displayed. The time stamps corresponding to T1, T2 and their delta are shown in the status line when the mouse is hovering over the control flow.
-
-Arrows can be displayed that follow the execution of each CPU across processes. The arrows indicate when the scheduler switches from one process to another for a given CPU. The CPU being followed is indicated on the state tooltip. When the scheduler switches to and from the idle process, the arrow skips to the next process which executes on the CPU after the idle process. Note that an appropriate zoom level is required for all arrows to be displayed.
-
-The display of arrows is optional and can be toggled using the '''Hide Arrows''' toolbar button. It is also possible to follow a CPU's execution across state changes and the scheduler's process switching using the '''Follow CPU Forward/Backward''' toolbar buttons.
-
-==== Using the mouse ====
-
-The states flow is usable with the mouse. The following actions are set:
-
-* '''left-click''': select a time or time range begin time
-* '''Shift-left-click''': select a time range end time
-* '''left-drag horizontally''': select a time range or change the time range begin or end time
-* '''middle-drag or Ctrl-left-drag horizontally''': pan left or right
-* '''right-drag horizontally''': [[#Zoom region|zoom region]]
-* '''click on a colored bar''': the associated process node is selected and the current time indicator is moved where the click happened
-* '''mouse wheel up/down''': scroll up or down
-* '''Ctrl-mouse wheel up/down''': zoom in or out
-* '''drag the time ruler horizontally''': zoom in or out with fixed start time
-* '''double-click the time ruler''': reset zoom to full range
-
-When the current time indicator is changed (when clicking in the states flow), all the other views are '''synchronized'''. For example, the [[#LTTng Kernel Events Editor|Events Editor]] will show the event matching the current time indicator. The reverse behaviour is also implemented: selecting an event within the Events View will update the Control Flow View current time indicator.
-
-==== Incomplete regions ====
-
-You'll notice '''small dots''' over the colored bars at some places:
-
-[[Image:images/Cfv_small_dots.png]]
-
-Those dots mean the underlying region is '''incomplete''': there's not enough pixels to view all the events. In other words, you have to zoom in.
-
-When zooming in, small dots start to disappear:
-
-[[Image:images/Cfv_zoom.png]]
-
-When no dots are left, you are viewing '''all the events and states''' within that region.
-
-==== Zoom region ====
-
-To zoom in on a specific region, '''right-click and drag''' in order to draw a time range:
-
-[[Image:images/Cfv_zoom_region.png]]
-
-The states flow horizontal space will only show the selected region.
-
-==== Tooltips ====
-
-Hover the cursor over a colored bar and a '''tooltip''' will pop up:
-
-[[Image:images/Cfv_tooltip.png]]
-
-The tooltip indicates:
-
-* the process name
-* the pointed state name
-* the CPU (if applicable)
-* the system call name (if applicable)
-* the pointed state date and start/stop times
-* the pointed state duration (seconds)
-
-=== Toolbar ===
-
-The Control Flow View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
-
-{|
-| [[Image:images/filter_items.gif]]
-| Show View Filter
-| Opens the process filter dialog
-|-
-| [[Image:images/show_legend.gif]]
-| Show Legend
-| Displays the states legend
-|-
-| [[Image:images/home_nav.gif]]
-| Reset the Time Scale to Default
-| Resets the zoom window to the full range
-|-
-| [[Image:images/prev_event.gif]]
-| Select Previous Event
-| Selects the previous state for the selected process
-|-
-| [[Image:images/next_event.gif]]
-| Select Next Event
-| Selects the next state for the selected process
-|-
-| [[Image:images/prev_menu.gif]]
-| Select Previous Process
-| Selects the previous process
-|-
-| [[Image:images/next_menu.gif]]
-| Select Next Process
-| Selects the next process
-|-
-| [[Image:images/zoomin_nav.gif]]
-| Zoom In
-| Zooms in on the selection by 50%
-|-
-| [[Image:images/zoomout_nav.gif]]
-| Zoom Out
-| Zooms out on the selection by 50%
-|-
-| [[Image:images/hide_arrows.gif]]
-| Hide Arrows
-| Toggles the display of arrows on or off
-|-
-| [[Image:images/follow_arrow_bwd.gif]]
-| Follow CPU Backward
-| Selects the previous state following CPU execution across processes
-|-
-| [[Image:images/follow_arrow_fwd.gif]]
-| Follow CPU Forward
-| Selects the next state following CPU execution across processes
-|}
-
-== Resources View ==
-
-This view is specific to LTTng kernel traces. The LTTng Kernel analysis is executed the first time a LTTng Kernel is opened. After opening the trace, the element '''Resources''' is added under the '''LTTng Kernel Analysis''' tree element of the Project Explorer. To open the view, double-click the '''Resources''' tree element.
-
-Alternatively, go in '''Window''' -> '''Show View''' -> '''Other...''' and select '''LTTng/Resources''' in the list.
-
-[[Image:images/Rv_example.png|Example of resources view with all trace points and syscalls enabled]]
-
-This view shows the state of system resources i.e. if changes occured during the trace either on '''CPUs''', '''IRQs''' or '''soft IRQs''', it will appear in this view. The left side of the view present a list of resources that are affected by at least one event of the trace. The right side illustrate the state in which each resource is at some point in time. For state '''USERMODE''' it also prints the process name in the state bar. For state '''SYSCALL''' the name of the system call is
-displayed in the state region.
-
-Just like other views, according to which trace points and system calls are activated, the content of this view may change from one trace to another.
-
-Each state are represented by one color so it is faster to say what is happening.
-
-[[Image:images/Rv_legend.png|Color for each state]]
-
-To go through the state of a resource, you first have to select the resource and the timestamp that interest you. For the latter, you can pick some time before the interesting part of the trace.
-
-[[Image:images/RV_infobox1.png|Shows the state of an IRQ]]
-
-Then, by selecting '''Next Event''', it will show the next state transition and the event that occured at this time.
-
-[[Image:images/RV_infobox2.png|Shows the next state of the IRQ]]
-
-This view is also synchronized with the others : [[#Histogram_View | Histogram View]], [[#LTTng_Kernel_Events_Editor | Events Editor]], [[#Control_Flow_View | Control Flow View]], etc.
-
-=== Navigation ===
-
-See Control Flow View's '''[[#Using_the_mouse | Using the mouse]]''' and '''[[#Zoom_region | Zoom region]]'''.
-
-=== Incomplete regions ===
-
-See Control Flow View's '''[[#Incomplete_regions | Incomplete regions]]'''.
-
-=== Toolbar ===
-
-The Resources View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
-
-{|
-| [[Image:images/show_legend.gif]]
-| Show Legend
-| Displays the states legend
-|-
-| [[Image:images/home_nav.gif]]
-| Reset the Time Scale to Default
-| Resets the zoom window to the full range
-|-
-| [[Image:images/prev_event.gif]]
-| Select Previous Event
-| Selects the previous state for the selected resource
-|-
-| [[Image:images/next_event.gif]]
-| Select Next Event
-| Selects the next state for the selected resource
-|-
-| [[Image:images/prev_menu.gif]]
-| Select Previous Resource
-| Selects the previous resource
-|-
-| [[Image:images/next_menu.gif]]
-| Select Next Resource
-| Selects the next resource
-|-
-| [[Image:images/zoomin_nav.gif]]
-| Zoom In
-| Zooms in on the selection by 50%
-|-
-| [[Image:images/zoomout_nav.gif]]
-| Zoom Out
-| Zooms out on the selection by 50%
-|}
-
-== LTTng CPU Usage View ==
-
-The CPU Usage analysis and view is specific to LTTng Kernel traces. The CPU usage is derived from a kernel trace as long as the '''sched_switch''' event was enabled during the collection of the trace. This analysis is executed the first time that the CPU Usage view is opened after opening the trace. To open the view, double-click on the '''CPU Usage''' tree element under the '''LTTng Kernel Analysis''' tree element of the Project Explorer.
-
-[[Image:images/LTTng_OpenCpuUsageView.png]]
-
-Now, the CPU Usage view will show:
-
-[[Image:images/LTTng_CpuUsageView.png]]
-
-The view is divided into the following important sections: '''Process Information''' and the '''CPU Usage Chart'''.
-
-
-=== Process Information ===
-The Process Information is displayed on the left side of the view and shows all threads that were executing on all available CPUs in the current time range. For each process, it shows in different columns the thread ID (TID), process name (Process), the average (%) execution time and the actual execution time (Time) during the current time range. It shows all threads that were executing on the CPUs in the current time range.
-
-
-=== CPU Usage Chart ===
-
-The CPU Usage Chart on the right side of the view, plots the total time spent on all CPUs of all processes and the time of the selected process.
-
-
-==== Using the mouse ====
-
-The CPU Usage chart is usable with the mouse. The following actions are set:
-
-* '''left-click''': select a time or time range begin time
-* '''Shift-left-click''': select a time range end time
-* '''left-drag horizontally''': select a time range or change the time range begin or end time
-* '''middle-drag''': pan left or right
-* '''right-drag horizontally''': zoom region
-* '''mouse wheel up/down''': zoom in or out
-
-
-==== Tooltips ====
-
-Hover the cursor over a line of the chart and a tooltip will pop up with the following information:
-* '''time''': current time of mouse position
-* '''Total''': The total CPU usage
-
-
-[[Image:images/LTTng_CpuUsageViewToolTip.png]]
-
-
-== LTTng Kernel Events Editor ==
-
-The LTTng Kernel Events editor '''is''' the plain TMF [[#Events_Editor | Events Editor]], except that it provides its own specialized viewer to replace the standard one. In short, it has exactly the same behaviour but the layout is slightly different:
-
-* '''Timestamp''': the event timestamp
-* '''Channel''': the event channel (data collector)
-* '''Event Type''': the event type (or kernel marker)
-* '''Content''': the raw event content
-
-[[Image:images/LTTng2EventsEditor.png]]
-
-= LTTng-UST Analyses =
-
-The Userspace traces are taken on an application level. With kernel traces, you know what events you will have as the domain is known and cloistered. Userspace traces can contain pretty much anything. Some analyses are offered if certain events are enabled.
-
-== Call Stack View ==
-
-The Call Stack view allows the user to visualize the call stack per thread over time, if the application and trace provide this information.
-
-To open this view go in '''Window''' -> '''Show View''' -> '''Other...''' and select '''Tracing/Call Stack''' in the list. The view shows the call stack information for the currently selected trace. Conversely, you can select a trace and expand it in the '''Project Explorer''' then expand '''LTTng-UST CallStack Analysis''' (the trace must be loaded) and open '''Call Stack'''.
-
-The table on the left-hand side of the view shows the threads and call stack. The function name, depth, entry and exit time and duration are shown for the call stack at the selected time.
-
-Double-clicking on a function entry in the table will zoom the time graph to the selected function's range of execution.
-
-The time graph on the right-hand side of the view shows the call stack state graphically over time. The function name is visible on each call stack event if size permits. The color of each call stack event is randomly assigned based on the function name, allowing for easy identification of repeated calls to the same function.
-
-Clicking on the time graph will set the current time and consequently update the table with the current call stack information.
-
-Shift-clicking on the time graph will select a time range. When the selection is a time range, the begin time is used to update the stack information.
-
-Double-clicking on a call stack event will zoom the time graph to the selected function's range of execution.
-
-Clicking the '''Select Next Event''' or '''Select Previous Event''' or using the left and right arrows will navigate to the next or previous call stack event, and select the function currently at the top of the call stack.
-
-Clicking the '''Import Mapping File''' ([[Image:images/import.gif]]) icon will open a file selection dialog, allowing you to import a text file containing mappings from function addresses to function names. If the callstack provider for the current trace type only provides function addresses, a mapping file will be required to get the function names in the view. See the following sections for an example with LTTng-UST traces.
-
-=== Using the Callstack View with LTTng-UST traces ===
-
-There is support in the LTTng-UST integration plugin to display the callstack of applications traced with the ''liblttng-ust-cyg-profile.so'' library (see the ''liblttng-ust-cyg-profile'' man page for additional information). To do so, you need to:
-
-* Recompile your application with "''-g -finstrument-functions''".
-* Add the ''vtid'' and ''procname'' contexts to your trace session. See the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
-** <pre>lttng add-context -u -t vtid -t procname</pre>
-* Preload the ''liblttng-ust-cyg-profile'' library when running your program:
-** <pre>LD_PRELOAD=/usr/lib/liblttng-ust-cyg-profile.so ./myprogram</pre>
-
-Once you load the resulting trace, making sure it's set to the ''Common Trace Format - LTTng UST Trace'' type, the Callstack View should be populated with the relevant information. However, since GCC's cyg-profile instrumentation only provides function addresses, and not names, an additional step is required to get the function names showing in the view. The following section explains how to do so.
-
-=== Importing a function name mapping file for LTTng-UST traces ===
-
-If you followed the steps in the previous section, you should have a Callstack View populated with function entries and exits. However, the view will display the function addresses instead of names in the intervals, which are not very useful by themselves. To get the actual function names, you need to:
-
-* Generate a mapping file from the binary, using:
-** <pre>nm myprogram > mapping.txt</pre>
-* Click the '''Import Mapping File''' ([[Image:images/import.gif]]) button in the Callstack View, and select the ''mapping.txt'' file that was just created.
-
-The view should now update to display the function names instead. Make sure the binary used for taking the trace is the one used for this step too (otherwise, there is a good chance of the addresses not being the same).
-
-== Memory Usage ==
-
-The Memory Usage view allows the user to visualize the active memory usage per thread over time, if the application and trace provide this information.
-
-The view shows the memory consumption for the currently selected trace.
-
-The time chart plots heap memory usage graphically over time. There is one line per process, unassigned memory usage is mapped to "Other".
-
-In this implementation, the user needs to trace while hooking the ''liblttng-ust-libc-wrapper'' by running ''LD_PRELOAD=liblttng-ust-libc-wrapper.so'' '''<exename>'''. This will add tracepoints to memory allocation and freeing to the heap, NOT shared memory or stack usage. If the contexts '''vtid''' and '''procname''' are enabled, then the view will associate the heap usage to processes. As detailed earlier, to enable the contexts, see the [[#Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
-* <pre>lttng add-context -u -t vtid -t procname</pre>
-
-If thread information is available the view will look like this:
-
-[[Image:images/memoryUsage/memory-usage-multithread.png]]
-
-If thread information is not available it will look like this:
-
-[[Image:images/memoryUsage/memory-usage-no-thread-info.png]]
-
-The view allows selection of a specific time by left-clicking on a point in the chart. Left mouse dragging will select a time range. Right mouse dragging on the area will zoom in on that window. Middle mouse dragging will move the display window. Mouse wheel operations will zoom in and out also.
-
-Please note this view will not show shared memory or stack memory usage.
-
-= Trace synchronization =
-
-It is possible to synchronize traces from different machines so that they have the same time reference. Events from the reference trace will have the same timestamps as usual, but the events from traces synchronized with the first one will have their timestamps transformed according to the formula obtained after synchronization.
-
-== Obtain synchronizable traces ==
-
-To synchronize traces from different machines, they need to exchange packets through the network and have events enabled such that the data can be matched from one trace to the other. For now, only TCP packets can be matched between two traces.
-
-LTTng traces that can be synchronized are obtained using one of two methods (both methods are compatible):
-
-=== LTTng-module network tracepoint with complete data ===
-
-The tracepoints '''net_dev_queue''' and '''netif_receive_skb''' will be used for synchronization. Both tracepoints are available in lttng-modules since version 2.2, but they do not contain sufficient data to be used to synchronize traces.
-
-An experimental branch introduces this extra data: lttng-modules will need to be compiled by hand.
-
-Obtain the source code for the experimental lttng-modules
-
- # git clone git://git.dorsal.polymtl.ca/~gbastien/lttng-modules.git
- # cd lttng-modules
-
-Checkout the ''net_data_experimental'' branch, compile and install lttng-modules as per the lttng-modules documentation
-
- # git checkout net_data_experimental
- # make
- # sudo make modules_install
- # sudo depmod -a
-
-This experimental branch adds IP, IPv6 and TCP header data to the tracepoints. Packets received and sent with other protocols do not have this extra header data, but all packets are captured.
-
-=== LTTng-modules addons kernel module with dynamic tracepoints ===
-
-This method adds dynamic instrumentation on TCP packets via extra kernel modules. Only TCP packets are captured.
-
-Obtain the source code, along with lttng-modules
-
- # git clone https://github.com/giraldeau/lttng-modules.git
- # cd lttng-modules
-
-Checkout the addons branch, compile and install lttng-modules as per the lttng-modules documentation. The ''make'' command will fail at first with a message about the unset SYSMAP variable. Instructions on how to generate a System.map are mentioned in the error message.
-
- # git checkout addons
- # make
- # (follow the instructions to obtain the System.map file and set the SYSMAP variable)
- # make
- # sudo make modules_install
- # sudo depmod -a
-
-The lttng-addons modules must be inserted manually for the TCP tracepoints to be made available.
-
- # sudo modprobe lttng-addons
- # sudo modprobe lttng-probe-addons
-
-The following tracepoints will be available
-
- # sudo lttng list -k
- Kernel events:
- -------------
- ...
- inet_sock_create (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- inet_sock_delete (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- inet_sock_clone (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- inet_accept (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- inet_connect (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- inet_sock_local_in (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- inet_sock_local_out (loglevel: TRACE_EMERG (0)) (type: tracepoint)
- ...
-
-The ones used for trace synchronization are '''inet_sock_local_in''' and '''inet_sock_local_out'''.
-
-== Synchronize traces in TMF ==
-
-In order to synchronize traces, create a new experiment and select all traces that need to be synchronized. Right-click on the experiment and select '''Synchronize traces'''. For each trace whose time needs to be transformed, a new trace named as the original but followed by a '_' will be created with the transformed timestamps, and the original trace will be replaced in the experiment. The original trace can still be accessed under the '''Traces''' folder.
-
-[[Image:images/Sync_menu.png|Right-click synchronize traces to perform the trace synchronization]]
-
-When opening the experiment now, all the views will be synchronized. The following screenshot presents the differences in the filtered Control Flow View before and after the time synchronization.
-
-[[Image:images/Sync_cfv.png|Example of Control Flow View before and after trace synchronization]]
-
-Information on the quality of the synchronization, the timestamp transformation formula and some synchronization statistics can be visualized in the '''Synchronization''' view. To open the '''Synchronization''' view, use the Eclipse Show View dialog ('''Window''' -> '''Show View''' -> '''Other...'''). Then select '''Synchronization''' under '''Tracing'''.
-
-[[Image:images/Sync_view.png|Example of Synchronization view]]
-
-= Time offsetting =
-
-The time offsetting feature allows the user to apply a fixed offset to all event timestamps in a trace. It can be used, for example, to adjust the start time of a trace, or to manually align the timestamp of events from different traces.
-
-== Basic mode ==
-
-If the time offset to apply is known, it can be applied directly to the trace. In the '''Project Explorer''' view, select a trace, right-click and select '''Apply Time Offset...'''. It is also possible to select multiple traces, experiments or trace folders. All contained traces will be selected.
-
-[[Image:images/TimeOffsetApply.png|Apply Time Offset menu]]
-
-The dialog opens, in '''Basic''' mode.
-
-[[Image:images/TimeOffsetBasicDialog.png|Apply Time Offset dialog - Basic mode]]
-
-Enter a time offset to apply in the '''Offset in seconds''' column, with or without decimals. Then press the '''OK''' button.
-
-[[Image:images/TimeOffsetBasicDialogFilled.png|Apply Time Offset dialog - Basic mode - filled]]
-
-The time offset is applied to the trace and can be seen in the '''time offset''' property in the '''Properties''' view when the trace is selected.
-
-The applied time offset is added to any time offset or time transformation formula currently set for the trace, and the resulting offset replaces any previous setting.
-
-== Advanced mode ==
-
-The time offset can also be computed using selected trace events or manually entered timestamps. After selecting one or more traces in the '''Project Explorer''' view, right-click and select '''Apply Time Offset...'''. In the opened dialog, select the '''Advanced''' button.
-
-[[Image:images/TimeOffsetAdvancedDialog.png|Apply Time Offset dialog - Advanced mode]]
-
-Double-clicking a trace name will open the trace in an editor. The '''Reference Time''' will be set to the trace start time. Selecting any event in the trace editor will set the '''Reference Time''' for that trace to the event's timestamp.
-
-Selecting an event or a time in any view or editor that supports time synchronization will set the '''Target Time''' for every trace in the dialog.
-
-Pressing the '''<<''' button will compute the time offset that should be applied in order to make the reference time align to the target time, provided that both fields are set.
-
-The '''Reference Time''', '''Target Time''' and '''Offset in seconds''' fields can also be edited and entered manually.
-
-To synchronize two events from different traces, first select an event in the trace to which the time offset should be applied, which will set its '''Reference Time''' field.
-
-[[Image:images/TimeOffsetAdvancedSetReference.png|Apply Time Offset dialog - Set Reference Time]]
-
-Then select a corresponding event in the second trace, which will set the '''Target Time''' field for the first trace.
-
-[[Image:images/TimeOffsetAdvancedSetTarget.png|Apply Time Offset dialog - Set Target Time]]
-
-Finally, press the '''<<''' button, which will automatically compute the time offset that should be applied in order to make the first event's timestamp align to the second event's timestamp.
-
-[[Image:images/TimeOffsetAdvancedComputeOffset.png|Apply Time Offset dialog - Compute Offset]]
-
-Then press the '''OK''' button. The time offset is applied to the trace and can be seen in the '''time offset''' property in the '''Properties''' view when the trace is selected.
-
-The applied time offset is added to any time offset or time transformation formula currently set for the trace, and the resulting offset replaces any previous setting.
-
-[[Image:images/TimeOffsetProperty.png|Time Offset - Properties view]]
-
-== Clearing time offset ==
-
-The time offset previously applied can be cleared to reset the trace to its original timestamps. In the '''Project Explorer''' view, select a trace, right-click and select '''Clear Time Offset'''. It is also possible to select multiple traces, experiments or trace folders. All contained traces will be affected.
-
-The time offset or any time transformation formula will be deleted.
-
-= Timestamp formatting =
-
-Most views that show timestamps are displayed in the same time format. The unified timestamp format can be changed in the Preferences page. To get to that page, click on '''Window''' -> '''Preferences''' -> '''Tracing''' -> '''Time Format'''. Then a window will show the time format preferences.
-
-[[Image:images/TmfTimestampFormatPage.png]]
-
-The preference page has several subsections:
-
-* '''Current Format''' a format string generated by the page
-* '''Sample Display''' an example of a timestamp formatted with the '''Current Format''' string.
-* '''Time Zone''' the time zone to use when displaying the time. The value '''Local time''' corresponds to the local, system-configured, time zone.
-* '''Data and Time format''' how to format the date (days/months/years) and the time (hours/minutes/seconds)
-* '''Sub-second format''' how much precision is shown for the sub-second units
-* '''Date delimiter''' the character used to delimit the date units such as months and years
-* '''Time delimiter''' the character to separate super-second time units such as seconds and minutes
-* '''Sub-Second Delimiter''' the character to separate the sub-second groups such as milliseconds and nanoseconds
-* '''Restore Defaults''' restores the system settings
-* '''Apply''' apply changes
-
-This will update all the displayed timestamps.
-
-= Data driven analysis =
-
-It is possible to define custom trace analyses and a way to view them in an XML format. These kind of analyses allow doing more with the trace data than what the default analyses shipped with TMF offer. It can be customized to a specific problem, and fine-tuned to show exactly what you're looking for.
-
-== Importing an XML file containing analysis ==
-
-If you already have an XML file defining state providers and/or views, you can import it in your TMF workspace by right-clicking on the ''Traces'' or ''Experiments'' folder and selecting ''Import XML Analysis''.
-
-[[Image:images/import_XML_analysis.png| Import XML analysis menu]]
-
-You will be prompted to select the file. It will be validated before importing it and if successful, the new analysis and views will be shown under the traces for which they apply. You will need to close any already opened traces and re-open them before the new analysis can be executed.
-
-Right now, there is no way to "unimport" analyses from within the application. A UI to manage the imported analyses is currently being worked on. In the meantime, you can navigate to your workspace directory, and delete the files in .metadata/.plugins/org.eclipse.linuxtools.tmf.analysis.xml.core/xml_files .
-
-== Defining XML components ==
-
-To define XML components, you need to create a new XML file and use the XSD that comes with the XML plugin.
-
-''For now, the XSD is only available through the source code in org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd''.
-
-An empty file, with no content yet would look like this:
-
-<pre>
-<?xml version="1.0" encoding="UTF-8"?>
-<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:noNamespaceSchemaLocation="xmlDefinition.xsd">
-
-</tmfxml>
-</pre>
-
-== Defining an XML state provider ==
-
-The state system is a component of TMF which can track the states of different elements of the system over the duration of a trace. To build this state system, events have to go chronologically through a state provider, which defines what changes are caused by the event to the system.
-
-The state system obtained by the state provider can then be used to populate data-driven views without having to re-read the trace, or to query specific timestamps in the trace without needing to access the trace file.
-
-=== Definitions and example ===
-
-Before we start, we'll define a few terms used in the following sections. The interested reader should read the [[Developer-Guide|Tmf Developer Guide]] for more complete description of the state system and state providers.
-
-* The '''state system''' can be viewed as a model of the system, where the different elements (attributes) can be seen as a tree, and their evolution (states) is tracked through time.
-
-* '''Attribute''': An attribute is the smallest element of the model that can be in any particular state. Since many attributes may have the same name, each attribute is represented by its full path in the attribute tree.
-
-* '''State''': A state is a value assigned to an attribute at a given time. Each model has its own state values.
-
-* '''Attribute tree''': Elements in the model can be placed in a tree-like structure, for logical grouping. Each element in the tree can have both children and a state. Also, the tree is just a logical structure, all elements may be top-level elements.
-
-* '''State history''': Whereas the attribute tree may be seen as the first dimension of the state system, the state history is the second dimension, over time. It tracks the intervals at which an attribute was in a given state.
-
-In the following sections, we'll use an example trace with the following events:
-
-* start(number): A new task with ID 'number' just started.
-* execute(number, fct_name): The task with ID 'number' is executing a critical section named 'fct_name'.
-* wait(number): The task with ID 'number' cannot execute a critical section and needs to wait for it.
-* exec_end(fct_name): A task finished executing the critical section named 'fct_name'.
-* stop(number): The task with ID 'number' has just finished.
-
-=== Determining the state system structure ===
-
-The first thing to do is to determine the attribute tree we'll use to represent the model of the system. The attribute tree is like a file system with directories and files, where files are logically gathered in the same parent directory. There is no one good way to build a tree, the logic will depend on the situation and on the person defining it.
-
-The generated state system may be used later on to populate views, so attributes of the tree could be grouped in such a way as to make it easy to reach them with a simple path. The view will then be more simple.
-
-In our example case, we'll want to track the status of each task and, for each critical section, which task is running them.
-
-<pre>
-|- Tasks
-| |- 1
-| |- 2
-| ...
-|- Critical section
- |- Crit_sect1
- |- Crit_sect2
- ...
-</pre>
-
-Then we determine how each event will affect the state of the attributes. But first, let's ask ourselves what values should each state take.
-
-Let's see with the tree:
-
-<pre>
-|- Tasks -> Empty
-| |- 1 -> Each task can be in one of
-| |- 2 RUNNING, CRITICAL, WAITING
-| ...
-|- Critical section -> Empty
- |- Crit_sect1 -> Each critical section will hold the currently running task number
- |- Crit_sect2
- ...
-</pre>
-
-Then we determine how each event will affect the state of the attributes. In the attribute paths below, elements in {} are values coming from the trace event, while strings are constants. For the sake of simplicity, we'll say "update attribute", but if an attribute does not exist, it will be created.
-
-* start(number): Update state value of attribute "Tasks/{number}" to "RUNNING".
-* execute(number, fct_name): Update state value of attribute "Tasks/{number}" to "CRITICAL" and Update attribute "Critical section/{fct_name}" to "{number}".
-* wait(number): Update state value of attribute "Tasks/{number}" to "WAITING".
-* exec_end(fct_name): Update state value of attribute "Tasks/{valueOf Critical section/{fct_name}}" to RUNNING and update "Critical section/{fct_name}" to null.
-* stop(number): Update state value of attribute "Tasks/{number}" to null.
-
-=== Writing the XML state provider ===
-
-Once the model is done at a high level, it is time to translate it to an XML data-driven analysis. For details on how to use each XML element, refer to the documentation available in the XSD files. Some elements will be commented on below.
-
-First define the state provider element.
-
-The "version" attribute indicates which version of the state system is defined here. Once a state provider has been defined for a trace type, it will typically be used by a team of people and it may be modified over time. This version number should be bumped each time a new version of the state provider is published. This will force a rebuild of any existing state histories (if applicable) whose version number is different from the current one.
-
-The "id" attribute uniquely identifies this state provider, and the analysis that will contain it.
-
-<pre>
-<stateProvider version="0" id="my.test.state.provider">
-</pre>
-
-Optional header information can be added to the state provider. A "traceType" should be defined to tell TMF which trace type this analysis will apply to. If no tracetype is specified, the analysis will appear under every trace. A "label" can optionally be added to have a more user-friendly name for the analysis.
-
-<pre>
-<head>
- <traceType id="my.trace.id" />
- <label value="My test analysis" />
-</head>
-</pre>
-
-If pre-defined values will be used in the state provider, they must be defined before the state providers. They can then be referred to in the state changes by name, preceded by the '$' sign. It is not necessary to use pre-defined values, the state change can use values like (100, 101, 102) directly.
-
-<pre>
-<definedValue name="RUNNING" value="100" />
-<definedValue name="CRITICAL" value="101" />
-<definedValue name="WAITING" value="102" />
-</pre>
-
-The following event handler shows what to do with the event named ''start''. It causes one state change. The sequence of '''stateAttribute''' elements represents the path to the attribute in the attribute tree, each element being one level of the tree. The '''stateValue''' indicates which value to assign to the attribute at the given path. The "$RUNNING" value means it will use the predefined value named RUNNING above.
-
-Suppose the actual event is ''start(3)''. The result of this state change is that at the time of the event, the state system attribute "Tasks/3" will have value 100.
-
-<pre>
-<eventHandler eventName="start">
- <stateChange>
- <stateAttribute type="constant" value="Tasks" />
- <stateAttribute type="eventField" value="number" />
- <stateValue type="int" value="$RUNNING" />
- </stateChange>
-</eventHandler>
-</pre>
-
-The full XML file for the example above would look like this:
-
-<pre>
-<?xml version="1.0" encoding="UTF-8"?>
-<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
- <stateProvider version="0" id="my.test.state.provider">
- <head>
- <traceType id="my.trace.id" />
- <label value="My test analysis" />
- </head>
-
- <definedValue name="RUNNING" value="100" />
- <definedValue name="CRITICAL" value="101" />
- <definedValue name="WAITING" value="102" />
-
- <eventHandler eventName="start">
- <stateChange>
- <stateAttribute type="constant" value="Tasks" />
- <stateAttribute type="eventField" value="number" />
- <stateValue type="int" value="$RUNNING" />
- </stateChange>
- </eventHandler>
- <eventHandler eventName="execute">
- <stateChange>
- <stateAttribute type="constant" value="Tasks" />
- <stateAttribute type="eventField" value="number" />
- <stateValue type="int" value="$CRITICAL" />
- </stateChange>
- <stateChange>
- <stateAttribute type="constant" value="Critical section" />
- <stateAttribute type="eventField" value="fct_name" />
- <stateValue type="eventField" value="number" />
- </stateChange>
- </eventHandler>
- <eventHandler eventName="wait">
- <stateChange>
- <stateAttribute type="constant" value="Tasks" />
- <stateAttribute type="eventField" value="number" />
- <stateValue type="int" value="$WAITING" />
- </stateChange>
- </eventHandler>
- <eventHandler eventName="exec_end">
- <stateChange>
- <stateAttribute type="constant" value="Tasks" />
- <stateAttribute type="query">
- <stateAttribute type="constant" value="Critical section" />
- <stateAttribute type="eventField" value="fct_name" />
- </stateAttribute>
- <stateValue type="int" value="$RUNNING" />
- </stateChange>
- <stateChange>
- <stateAttribute type="constant" value="Critical section" />
- <stateAttribute type="eventField" value="fct_name" />
- <stateValue type="null" />
- </stateChange>
- </eventHandler>
- <eventHandler eventName="stop">
- <stateChange>
- <stateAttribute type="constant" value="Tasks" />
- <stateAttribute type="eventField" value="number" />
- <stateValue type="null" />
- </stateChange>
- </eventHandler>
- </stateProvider>
-</tmfxml>
-</pre>
-
-=== Debugging the XML state provider ===
-
-To debug the state system that was generated by the XML state provider, one could use the [[#State System Explorer View | State System Explorer View]], along with the events editor. By selecting an event, you can see what changes this event caused and the states of other attributes at the time.
-
-If there are corrections to make, you may modify the XML state provider file, and re-import it. To re-run the analysis, you must first delete the supplementary files by right-clicking on your trace, and selecting ''Delete supplementary files...''. Check you analysis's .ht file, so that the analysis will be run again when the trace is reopened. The supplementary file deletion will have closed the trace, so it needs to be opened again to use the newly imported analysis file.
-
-If modifications are made to the XML state provider after it has been "published", the '''version''' attribute of the '''xmlStateProvider''' element should be updated. This avoids having to delete each trace's supplementary file manually. If the saved state system used a previous version, it will automatically be rebuilt from the XML file.
-
-== Defining an XML time graph view ==
-
-A time graph view is a view divided in two, with a tree viewer on the left showing information on the different entries to display and a Gantt-like viewer on the right, showing the state of the entries over time. The [[#Control_Flow_View | Control Flow View]] is an example of a time graph view.
-
-Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
-
-In the example above, suppose we want to display the status for each task. In the state system, it means the path of the entries to display is "Tasks/*". The attribute whose value should be shown in the Gantt chart is the entry attribute itself. So the XML to display these entries would be as such:
-
-<pre>
-<entry path="Tasks/*">
- <display type="self" />
-</entry>
-</pre>
-
-But first, the view has to be declared. It has an ID, to uniquely identify this view among all the available XML files.
-
-<pre>
-<timeGraphView id="my.test.time.graph.view">
-</pre>
-
-Optional header information can be added to the view. '''analysis''' elements will associate the view only to the analysis identified by the "id" attribute. It can be either the ID of the state provider, like in this case, or the analysis ID of any analysis defined in Java. If no analysis is specified, the view will appear under every analysis with a state system. The '''label''' element allows to give a more user-friendly name to the view. The label does not have to be unique. As long as the ID is unique, views for different analyses can use the same name.
-
-<pre>
-<head>
- <analysis id="my.test.state.provider" />
- <label value="My Sample XML View" />
-</head>
-</pre>
-
-Also, if the values of the attributes to display are known, they can be defined, along with a text to explain them and a color to draw them with. Note that the values are the same as defined in the state provider, but the name does not have to be the same. While in the state provider, a simple constant string makes sense to use in state changes. But in the view, the name will appear in the legend, so a user-friendly text is more appropriate.
-
-<pre>
-<definedValue name="The process is running" value="100" color="#118811" />
-<definedValue name="Critical section" value="101" color="#881111" />
-<definedValue name="Waiting for critical section" value="102" color="#AEB522" />
-</pre>
-
-Here is the full XML for the time graph view:
-
-<pre>
-<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
- <timeGraphView id="my.test.time.graph.view">
- <head>
- <analysis id="my.test.state.provider" />
- <label value="My Sample XML View" />
- </head>
-
- <definedValue name="The process is running" value="100" color="#118811" />
- <definedValue name="Critical section" value="101" color="#881111" />
- <definedValue name="Waiting for critical section" value="102" color="#AEB522" />
-
- <entry path="Tasks/*">
- <display type="self" />
- </entry>
- </timeGraphView>
-</tmfxml>
-</pre>
-
-The following screenshot shows the result of the preceding example on a test trace. The trace used, as well as the XML file are available [http://secretaire.dorsal.polymtl.ca/~gbastien/Xml4Traces/XML_documentation_example.tar.gz here].
-
-[[Image:images/Xml_analysis_screenshot.png| XML analysis with view]]
-
-== Defining an XML XY chart ==
-
-An XY chart displays series as a set of numerical values over time. The X-axis represents the time and is synchronized with the trace's current time range. The Y-axis can be any numerical value.
-
-Such views can be defined in XML using the data in the state system. The state system itself could have been built by an XML-defined state provider or by any pre-defined Java analysis. It only requires knowing the structure of the state system, which can be explored using the [[#State System Explorer View | State System Explorer View]] (or programmatically using the methods in ''ITmfStateSystem'').
-
-We will use the LTTng Kernel Analysis on LTTng kernel traces to show an example XY chart. In this state system, the status of each CPU is a numerical value. We will display this value as the Y axis of the series. There will be one series per CPU. The XML to display these entries would be as such:
-
-<pre>
-<entry path="CPUs/*">
- <display type="constant" value="Status" />
- <name type="self" />
-</entry>
-</pre>
-
-But first, the view has to be declared. It has an ID, to uniquely identify this view among all the available XML files.
-
-<pre>
-<xyView id="my.test.xy.chart.view">
-</pre>
-
-Like for the time graph views, optional header information can be added to the view. '''analysis''' elements will associate the view only to the analysis identified by the "id" attribute. It can be either the ID of the state provider, like in this case, or the analysis ID of any analysis defined in Java. If no analysis is specified, the view will appear under every analysis with a state system. The '''label''' element allows to give a more user-friendly name to the view. The label does not have to be unique. As long as the ID is unique, views for different analyses can use the same name.
-
-<pre>
-<head>
- <analysis id="org.eclipse.linuxtools.lttng2.kernel.analysis" />
- <label value="CPU status XY view" />
-</head>
-</pre>
-
-Here is the full XML for the XY Chart that displays the CPU status over time of an LTTng Kernel Trace:
-
-<pre>
-<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.linuxtools.tmf.analysis.xml.core/src/org/eclipse/linuxtools/tmf/analysis/xml/core/module/xmlDefinition.xsd">
- <xyView id="my.test.xy.chart.view">
- <head>
- <analysis id="org.eclipse.linuxtools.lttng2.kernel.analysis" />
- <label value="CPU status XY view" />
- </head>
-
- <entry path="CPUs/*">
- <display type="constant" value="Status" />
- <name type="self" />
- </entry>
- </xyView>
-</tmfxml>
-</pre>
-
-The following screenshot shows the result of the preceding example on a LTTng Kernel Trace.
-
-[[Image:images/XML_xy_chart.png| XML XY chart]]
-
-= Limitations =
-
-* When parsing text traces, the timestamps are assumed to be in the local time zone. This means that when combining it to CTF binary traces, there could be offsets by a few hours depending on where the traces were taken and where they were read.
-* LTTng Tools v2.1.0 introduced the command line options ''--no-consumer'' and ''--disable-consumer'' for session creation as well as the commands ''enable-consumer'' and ''disable-consumer''. The LTTng Tracer Control in Eclipse doesn't support these options and commands because they will obsolete in LTTng Tools v2.2.0 and because the procedure for session creation offers already all relevant advanced parameters.
-
-= How to use LTTng to diagnose problems =
-
-LTTng is a tracer, it will give an enormous amount of information about the system it is running on. This means it can solve many types of problems.
-
-The following are examples of problems that can be solved with a tracer.
-
-== Random stutters ==
-
-Bob is running a computer program and it stutters periodically every 2 minutes. The CPU load is relatively low and Bob isn't running low on RAM.
-
-He decides to trace his complete system for 10 minutes. He opens the LTTng view in eclipse. From the control, he creates a session and enables all kernel tracepoints.
-
-He now has a 10 GB trace file. He imports the trace to his viewer and loads it up.
-
-A cursory look at the histogram bar on the bottom show relatively even event distribution, there are no interesting spikes, so he will have to dig deeper to find the issue. If he had seen a spike every 2 minutes, there would be strong chances this would be the first thing to investigate as it would imply a lot of kernel activity at the same period as his glitch, this would have been a path to investigate.
-
-As Bob suspects that he may be having some hardware raising IRQs or some other hardware based issue and adding delays. He looks at the ressource view and doesn't see anything abnormal.
-
-Bob did note an exact second one glitch occured: 11:58:03. He zooms into the time range or 11:58:02-11:58:04 using the histogram.He is happy to see the time is human readable local wall clock time and no longer in "nanseconds since the last reboot". <br>In the resource view, once again, he sees many soft irqs being raised at the same time, around the time his gui would freeze. He changes views and looks at the control flow view at that time and sees a process spending a lot of time in the kernel: FooMonitor- his temperature monitoring software.
-
-At this point he closes FooMonitor and notices the bug dissapeared. He could call it a day but he wants to see what was causing the system to freeze. He cannot justify closing a piece of software without understanding the issue. It may be a conflict that HIS software is causing after all.
-
-The system freezes around the time this program is running. He clicks on the process in the control flow view and looks at the corresponding events in the detailed events view. He sees: open - read - close repeated hundreds of times on the same file. The file being read was /dev/HWmonitor. He sends a report to the FooMonitor team and warns his team that FooMonitor was glitching their performance.
-
-The FooMonitor team finds that they were calling a system bus call that would halt a cpu while reading the temperature so that the core would not induce an 0.1 degree error in the reading, by disabling this feature, they improve their software and stop the glitches from occurring on their custommer's machine. They also optimize their code to open the file read and clone it once.
-
-By using system wide kernel tracing, even without deep kernel knowledge Bob was able to isolate a bug in a rogue piece of software in his system.
-
-== Slow I/O ==
-
-Alice is running her server. She noticed that one of her nodes was slowing down, and wasn't sure why, upon reading the trace she noticed that her time between a block request and complete was around 10ms.
-
-This is abnormal, normally her server handles IOs in under 100us, since they are quite local.
-
-She walks up to the server and hears the hard drive thrashing, This prompts her to look up in the events view the sectors being read in the block complete requests. There are her requests interleaved with other ones at the opposite side of the hard drive.
-
-She sees the tracer writing but there is another process that is writing to the server disk non stop. She looks in the control flow view and sees that there's a program from another fellow engineer, "Wally" that is writing in his home in a loop "All work and no play makes Jack a dull boy.".
-
-Alice kills the program, and immediately the server speeds up. She then goes to discuss this with Wally and implements strict hard disk quotas on the server.
-
-= References =
-
-* [http://www.eclipse.org/linuxtools/projectPages/lttng/ Linux Tools - LTTng integration]
-* [http://www.lttng.org/ LTTng project]
-* [http://lttng.org/files/doc/man-pages/man1/lttng.1.html LTTng Tracer Control Command Line Tool User Manual]
-* [http://lttng.org/files/doc/man-pages/man8/lttng-relayd.8.html LTTng relayd User Manual]
-* [http://wiki.eclipse.org/Linux_Tools_Project/TMF/User_Guide TMF User Guide]
-
-= Updating This Document =
-
-This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide]
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-Bundle-Vendor = Eclipse Trace Compass
-Bundle-Name = Trace Compass Help Plug-in
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<plugin>
-<!-- This part should be in a documentation plugin -->
-<!-- Configure the help contribution for this plugin -->
- <extension point="org.eclipse.help.toc">
- <toc
- file="doc/User-Guide-toc.xml"
- primary="true" />
- </extension>
-</plugin>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (C) 2011, Red Hat, Inc.
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <artifactId>org.eclipse.tracecompass</artifactId>
- <groupId>org.eclipse.tracecompass</groupId>
- <version>0.1.0-SNAPSHOT</version>
- </parent>
-
- <artifactId>org.eclipse.tracecompass.help</artifactId>
- <version>0.1.0-SNAPSHOT</version>
- <packaging>eclipse-plugin</packaging>
-
- <name>Trace Compass Help Plug-in</name>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-antrun-plugin</artifactId>
- <executions>
- <execution>
- <id>generate-documentation</id>
- <phase>generate-sources</phase>
- <configuration>
- <echo>Generating LTTng Help Files</echo>
- <target>
- <property name="compile_classpath" refid="maven.compile.classpath" />
- <ant target="build" inheritRefs="true" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- <execution>
- <id>clean-documentation</id>
- <phase>clean</phase>
- <configuration>
- <echo>Cleaning up generated LTTng Help Files</echo>
- <target>
- <ant target="clean" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- </executions>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-launcher</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-nodeps</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- </dependencies>
- </plugin>
- </plugins>
- </build>
-
- <groupId>org.eclipse.tracecompass</groupId>
-</project>
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>All Classes</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<h1 class="bar">All Classes</h1>\r
-<div class="indexContainer">\r
-<ul>\r
-<li><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp" target="classFrame">TmfTimestampFormat</a></li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>All Classes</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<h1 class="bar">All Classes</h1>\r
-<div class="indexContainer">\r
-<ul>\r
-<li><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>Constant Field Values</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<script type="text/javascript"><!--\r
- if (location.href.indexOf('is-external=true') == -1) {\r
- parent.document.title="Constant Field Values";\r
- }\r
-//-->\r
-</script>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<div class="header">\r
-<h1 title="Constant Field Values" class="title">Constant Field Values</h1>\r
-<h2 title="Contents">Contents</h2>\r
-<ul>\r
-<li><a href="#org.eclipse">org.eclipse.*</a></li>\r
-</ul>\r
-</div>\r
-<div class="constantValuesContainer"><a name="org.eclipse">\r
-<!-- -->\r
-</a>\r
-<h2 title="org.eclipse">org.eclipse.*</h2>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<table border="0" cellpadding="3" cellspacing="0" summary="Constant Field Values table, listing constant fields, and values">\r
-<caption><span>org.eclipse.linuxtools.tmf.core.timestamp.<a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></span><span class="tabEnd"> </span></caption>\r
-<tr>\r
-<th class="colFirst" scope="col">Modifier and Type</th>\r
-<th scope="col">Constant Field</th>\r
-<th class="colLast" scope="col">Value</th>\r
-</tr>\r
-<tbody>\r
-<tr class="altColor">\r
-<td class="colFirst"><a name="org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_INTERVAL_PATTERN">\r
-<!-- -->\r
-</a><code>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
-<td><code><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_INTERVAL_PATTERN">DEFAULT_INTERVAL_PATTERN</a></code></td>\r
-<td class="colLast"><code>"TTT.SSS SSS SSS"</code></td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><a name="org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_TIME_PATTERN">\r
-<!-- -->\r
-</a><code>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
-<td><code><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_TIME_PATTERN">DEFAULT_TIME_PATTERN</a></code></td>\r
-<td class="colLast"><code>"HH:mm:ss.SSS SSS SSS"</code></td>\r
-</tr>\r
-</tbody>\r
-</table>\r
-</li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>Deprecated List</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<script type="text/javascript"><!--\r
- if (location.href.indexOf('is-external=true') == -1) {\r
- parent.document.title="Deprecated List";\r
- }\r
-//-->\r
-</script>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<div class="header">\r
-<h1 title="Deprecated API" class="title">Deprecated API</h1>\r
-<h2 title="Contents">Contents</h2>\r
-<ul>\r
-<li><a href="#method">Deprecated Methods</a></li>\r
-</ul>\r
-</div>\r
-<div class="contentContainer"><a name="method">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<table border="0" cellpadding="3" cellspacing="0" summary="Deprecated Methods table, listing deprecated methods, and an explanation">\r
-<caption><span>Deprecated Methods</span><span class="tabEnd"> </span></caption>\r
-<tr>\r
-<th class="colOne" scope="col">Method and Description</th>\r
-</tr>\r
-<tbody>\r
-<tr class="altColor">\r
-<td class="colOne"><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultIntervalFormat(java.lang.String)">org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.setDefaultIntervalFormat(String)</a>\r
-<div class="block"><i>The default interval format pattern depends on the
- preferences, see <code>TmfTimePreferences</code>. To change the
- default time pattern, modify the preferences and call
- <a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
-</td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colOne"><a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultTimeFormat(java.lang.String)">org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.setDefaultTimeFormat(String)</a>\r
-<div class="block"><i>The default time pattern depends on the preferences, see
- <code>TmfTimePreferences</code>. To change the default time
- pattern, modify the preferences and call <a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
-</td>\r
-</tr>\r
-</tbody>\r
-</table>\r
-</li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>API Help</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<script type="text/javascript"><!--\r
- if (location.href.indexOf('is-external=true') == -1) {\r
- parent.document.title="API Help";\r
- }\r
-//-->\r
-</script>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<div class="header">\r
-<h1 class="title">How This API Document Is Organized</h1>\r
-<div class="subTitle">This API (Application Programming Interface) document has pages corresponding to the items in the navigation bar, described as follows.</div>\r
-</div>\r
-<div class="contentContainer">\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h2>Package</h2>\r
-<p>Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:</p>\r
-<ul>\r
-<li>Interfaces (italic)</li>\r
-<li>Classes</li>\r
-<li>Enums</li>\r
-<li>Exceptions</li>\r
-<li>Errors</li>\r
-<li>Annotation Types</li>\r
-</ul>\r
-</li>\r
-<li class="blockList">\r
-<h2>Class/Interface</h2>\r
-<p>Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:</p>\r
-<ul>\r
-<li>Class inheritance diagram</li>\r
-<li>Direct Subclasses</li>\r
-<li>All Known Subinterfaces</li>\r
-<li>All Known Implementing Classes</li>\r
-<li>Class/interface declaration</li>\r
-<li>Class/interface description</li>\r
-</ul>\r
-<ul>\r
-<li>Nested Class Summary</li>\r
-<li>Field Summary</li>\r
-<li>Constructor Summary</li>\r
-<li>Method Summary</li>\r
-</ul>\r
-<ul>\r
-<li>Field Detail</li>\r
-<li>Constructor Detail</li>\r
-<li>Method Detail</li>\r
-</ul>\r
-<p>Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.</p>\r
-</li>\r
-<li class="blockList">\r
-<h2>Annotation Type</h2>\r
-<p>Each annotation type has its own separate page with the following sections:</p>\r
-<ul>\r
-<li>Annotation Type declaration</li>\r
-<li>Annotation Type description</li>\r
-<li>Required Element Summary</li>\r
-<li>Optional Element Summary</li>\r
-<li>Element Detail</li>\r
-</ul>\r
-</li>\r
-<li class="blockList">\r
-<h2>Enum</h2>\r
-<p>Each enum has its own separate page with the following sections:</p>\r
-<ul>\r
-<li>Enum declaration</li>\r
-<li>Enum description</li>\r
-<li>Enum Constant Summary</li>\r
-<li>Enum Constant Detail</li>\r
-</ul>\r
-</li>\r
-<li class="blockList">\r
-<h2>Deprecated API</h2>\r
-<p>The <a href="deprecated-list.html">Deprecated API</a> page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.</p>\r
-</li>\r
-<li class="blockList">\r
-<h2>Prev/Next</h2>\r
-<p>These links take you to the next or previous class, interface, package, or related page.</p>\r
-</li>\r
-<li class="blockList">\r
-<h2>Frames/No Frames</h2>\r
-<p>These links show and hide the HTML frames. All pages are available with or without frames.</p>\r
-</li>\r
-<li class="blockList">\r
-<h2>All Classes</h2>\r
-<p>The <a href="allclasses-noframe.html">All Classes</a> link shows all classes and interfaces except non-static nested types.</p>\r
-</li>\r
-<li class="blockList">\r
-<h2>Serialized Form</h2>\r
-<p>Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.</p>\r
-</li>\r
-<li class="blockList">\r
-<h2>Constant Field Values</h2>\r
-<p>The <a href="constant-values.html">Constant Field Values</a> page lists the static final fields and their values.</p>\r
-</li>\r
-</ul>\r
-<em>This help file applies to API documentation generated using the standard doclet.</em></div>\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>Generated Documentation (Untitled)</title>\r
-<script type="text/javascript">\r
- targetPage = "" + window.location.search;\r
- if (targetPage != "" && targetPage != "undefined")\r
- targetPage = targetPage.substring(1);\r
- if (targetPage.indexOf(":") != -1 || (targetPage != "" && !validURL(targetPage)))\r
- targetPage = "undefined";\r
- function validURL(url) {\r
- var pos = url.indexOf(".html");\r
- if (pos == -1 || pos != url.length - 5)\r
- return false;\r
- var allowNumber = false;\r
- var allowSep = false;\r
- var seenDot = false;\r
- for (var i = 0; i < url.length - 5; i++) {\r
- var ch = url.charAt(i);\r
- if ('a' <= ch && ch <= 'z' ||\r
- 'A' <= ch && ch <= 'Z' ||\r
- ch == '$' ||\r
- ch == '_') {\r
- allowNumber = true;\r
- allowSep = true;\r
- } else if ('0' <= ch && ch <= '9'\r
- || ch == '-') {\r
- if (!allowNumber)\r
- return false;\r
- } else if (ch == '/' || ch == '.') {\r
- if (!allowSep)\r
- return false;\r
- allowNumber = false;\r
- allowSep = false;\r
- if (ch == '.')\r
- seenDot = true;\r
- if (ch == '/' && seenDot)\r
- return false;\r
- } else {\r
- return false;\r
- }\r
- }\r
- return true;\r
- }\r
- function loadFrames() {\r
- if (targetPage != "" && targetPage != "undefined")\r
- top.classFrame.location = top.targetPage;\r
- }\r
-</script>\r
-</head>\r
-<frameset cols="20%,80%" title="Documentation frame" onload="top.loadFrames()">\r
-<frame src="allclasses-frame.html" name="packageFrame" title="All classes and interfaces (except non-static nested types)">\r
-<frame src="org/eclipse/linuxtools/tmf/core/timestamp/package-summary.html" name="classFrame" title="Package, class and interface descriptions" scrolling="yes">\r
-<noframes>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<h2>Frame Alert</h2>\r
-<p>This document is designed to be viewed using the frames feature. If you see this message, you are using a non-frame-capable web client. Link to <a href="org/eclipse/linuxtools/tmf/core/timestamp/package-summary.html">Non-frame version</a>.</p>\r
-</noframes>\r
-</frameset>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>TmfTimestampFormat</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<script type="text/javascript"><!--\r
- if (location.href.indexOf('is-external=true') == -1) {\r
- parent.document.title="TmfTimestampFormat";\r
- }\r
-//-->\r
-</script>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<!-- ======== START OF CLASS DATA ======== -->\r
-<div class="header">\r
-<div class="subTitle">org.eclipse.linuxtools.tmf.core.timestamp</div>\r
-<h2 title="Class TmfTimestampFormat" class="title">Class TmfTimestampFormat</h2>\r
-</div>\r
-<div class="contentContainer">\r
-<ul class="inheritance">\r
-<li><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">java.lang.Object</a></li>\r
-<li>\r
-<ul class="inheritance">\r
-<li><a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true" title="class or interface in java.text">java.text.Format</a></li>\r
-<li>\r
-<ul class="inheritance">\r
-<li><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">java.text.DateFormat</a></li>\r
-<li>\r
-<ul class="inheritance">\r
-<li><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">java.text.SimpleDateFormat</a></li>\r
-<li>\r
-<ul class="inheritance">\r
-<li>org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-<div class="description">\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<dl>\r
-<dt>All Implemented Interfaces:</dt>\r
-<dd><a href="http://download.oracle.com/javase/7/docs/api/java/io/Serializable.html?is-external=true" title="class or interface in java.io">Serializable</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Cloneable.html?is-external=true" title="class or interface in java.lang">Cloneable</a></dd>\r
-</dl>\r
-<hr>\r
-<br>\r
-<pre>public class <span class="strong">TmfTimestampFormat</span>\r
-extends <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></pre>\r
-<div class="block">A formatting and parsing facility that can handle timestamps that span the
- epoch with a precision down to the nanosecond. It can be understood as an
- extension of SimpleDateFormat that supports seconds since the epoch (Jan 1,
- 1970, 00:00:00 GMT), additional sub-second patterns and optional delimiters.
- <p>
- The timestamp representation is broken down into a number of optional
- components that can be assembled into a fairly simple way.
-
- <h4>Date and Time Patterns</h4>
- All date and time pattern letters defined in <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text"><code>SimpleDateFormat</code></a> are
- supported with the following exceptions:
- <blockquote>
- <table border=0 cellspacing=3 cellpadding=0 >
- <tr bgcolor="#ccccff">
- <th align=left>Format
- <th align=left>Description
- <th align=left>Value Range
- <th align=left>Example
- <tr bgcolor="#eeeeff">
- <td><code>T</code>
- <td>The seconds since the epoch
- <td><code>0-9223372036</code>
- <td><code>1332170682</code>
- <tr>
- <td><code>S</code>
- <td>Millisecond
- <td><code>N/A</code>
- <td><code>Not supported</code>
- <tr bgcolor="#eeeeff">
- <td><code>W</code>
- <td>Week in month
- <td><code>N/A</code>
- <td><code>Not supported</code>
- </table>
- </blockquote>
- <p>
- <strong>Note:</strong> When parsing, if "T" is used, no other Date and Time
- pattern letter will be interpreted and the entire pre-delimiter input string
- will be parsed as a number. Also, "T" should be used for time intervals.
- <p>
- <strong>Note:</strong> The decimal separator between the Date and Time
- pattern and the Sub-Seconds pattern is mandatory (if there is a fractional
- part) and must be one of the sub-second delimiters. Date and Time pattern
- letters are not interpreted after the decimal separator.
- <p>
- <h4>Sub-Seconds Patterns</h4>
- <blockquote>
- <table border=0 cellspacing=3 cellpadding=0 >
- <tr bgcolor="#ccccff">
- <th align=left>Format
- <th align=left>Description
- <th align=left>Value Range
- <th align=left>Example
- <tr>
- <td><code>S</code>
- <td>Fraction of second
- <td><code>0-999999999</code>
- <td><code>123456789</code>
- <tr bgcolor="#eeeeff">
- <td><code>C</code>
- <td>Microseconds in ms
- <td><code>0-999</code>
- <td><code>456</code>
- <tr>
- <td><code>N</code>
- <td>Nanoseconds in µs
- <td><code>0-999</code>
- <td><code>789</code>
- </table>
- </blockquote>
- <strong>Note:</strong> The fraction of second pattern can be split, in which
- case parsing and formatting continues at the next digit. Digits beyond the
- total number of pattern letters are ignored when parsing and truncated when
- formatting.
- <p>
- <strong>Note:</strong> When parsing, "S", "C" and "N" are interchangeable
- and are all handled as fraction of second ("S"). The use of "C" and "N" is
- discouraged but is supported for backward compatibility.
- <p>
-
- The recognized sub-second delimiters are:
- <ul>
- <li>Space ("<code> </code>")
- <li>Period ("<code>.</code>")
- <li>Comma ("<code>,</code>")
- <li>Dash ("<code>-</code>")
- <li>Underline ("<code>_</code>")
- <li>Colon ("<code>:</code>")
- <li>Semicolon ("<code>;</code>")
- <li>Slash ("<code>/</code>")
- <li>Single-quote ("<code>''</code>")
- <li>Double-quote ("<code>"</code>")
- </ul>
- <p>
- <strong>Note:</strong> When parsing, sub-second delimiters are optional if
- unquoted. However, an extra delimiter or any other unexpected character in
- the input string ends the parsing of digits. All other quoted or unquoted
- characters in the sub-second pattern are matched against the input string.
-
- <h4>Examples</h4>
- The following examples show how timestamp patterns are interpreted in
- the U.S. locale. The given timestamp is 1332170682539677389L, the number
- of nanoseconds since 1970/01/01.
-
- <blockquote>
- <table border=0 cellspacing=3 cellpadding=0>
- <tr bgcolor="#ccccff">
- <th align=left>Date and Time Pattern
- <th align=left>Result
- <tr>
- <td><code>"yyyy-MM-dd HH:mm:ss.SSS.SSS.SSS"</code>
- <td><code>2012-03-19 11:24:42.539.677.389</code>
- <tr bgcolor="#eeeeff">
- <td><code>"yyyy-MM-dd HH:mm:ss.SSS.SSS"</code>
- <td><code>2012-03-19 11:24:42.539.677</code>
- <tr>
- <td><code>"yyyy-D HH:mm:ss.SSS.SSS"</code>
- <td><code>2012-79 11:24:42.539.677</code>
- <tr bgcolor="#eeeeff">
- <td><code>"ss,SSSS"</code>
- <td><code>42,5397</code>
- <tr>
- <td><code>"T.SSS SSS SSS"</code>
- <td><code>1332170682.539 677 389</code>
- <tr bgcolor="#eeeeff">
- <td><code>"T"</code>
- <td><code>1332170682</code>
- </table>
- </blockquote>
- <p></div>\r
-<dl><dt><span class="strong">Since:</span></dt>\r
- <dd>2.0</dd>\r
-<dt><span class="strong">Version:</span></dt>\r
- <dd>1.0</dd>\r
-<dt><span class="strong">Author:</span></dt>\r
- <dd>Francois Chouinard</dd>\r
-<dt><span class="strong">See Also:</span></dt><dd><a href="../../../../../../serialized-form.html#org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat">Serialized Form</a></dd></dl>\r
-</li>\r
-</ul>\r
-</div>\r
-<div class="summary">\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<!-- ======== NESTED CLASS SUMMARY ======== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="nested_class_summary">\r
-<!-- -->\r
-</a>\r
-<h3>Nested Class Summary</h3>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="nested_classes_inherited_from_class_java.text.DateFormat">\r
-<!-- -->\r
-</a>\r
-<h3>Nested classes/interfaces inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">DateFormat</a></h3>\r
-<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.Field.html?is-external=true" title="class or interface in java.text">DateFormat.Field</a></code></li>\r
-</ul>\r
-</li>\r
-</ul>\r
-<!-- =========== FIELD SUMMARY =========== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="field_summary">\r
-<!-- -->\r
-</a>\r
-<h3>Field Summary</h3>\r
-<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Field Summary table, listing fields, and an explanation">\r
-<caption><span>Fields</span><span class="tabEnd"> </span></caption>\r
-<tr>\r
-<th class="colFirst" scope="col">Modifier and Type</th>\r
-<th class="colLast" scope="col">Field and Description</th>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colFirst"><code>static <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_INTERVAL_PATTERN">DEFAULT_INTERVAL_PATTERN</a></strong></code>\r
-<div class="block">The default interval pattern</div>\r
-</td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><code>static <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#DEFAULT_TIME_PATTERN">DEFAULT_TIME_PATTERN</a></strong></code>\r
-<div class="block">The default timestamp pattern</div>\r
-</td>\r
-</tr>\r
-</table>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="fields_inherited_from_class_java.text.DateFormat">\r
-<!-- -->\r
-</a>\r
-<h3>Fields inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">DateFormat</a></h3>\r
-<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#AM_PM_FIELD" title="class or interface in java.text">AM_PM_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DATE_FIELD" title="class or interface in java.text">DATE_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DAY_OF_WEEK_FIELD" title="class or interface in java.text">DAY_OF_WEEK_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DAY_OF_WEEK_IN_MONTH_FIELD" title="class or interface in java.text">DAY_OF_WEEK_IN_MONTH_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DAY_OF_YEAR_FIELD" title="class or interface in java.text">DAY_OF_YEAR_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#DEFAULT" title="class or interface in java.text">DEFAULT</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#ERA_FIELD" title="class or interface in java.text">ERA_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#FULL" title="class or interface in java.text">FULL</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR_OF_DAY0_FIELD" title="class or interface in java.text">HOUR_OF_DAY0_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR_OF_DAY1_FIELD" title="class or interface in java.text">HOUR_OF_DAY1_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR0_FIELD" title="class or interface in java.text">HOUR0_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#HOUR1_FIELD" title="class or interface in java.text">HOUR1_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#LONG" title="class or interface in java.text">LONG</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MEDIUM" title="class or interface in java.text">MEDIUM</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MILLISECOND_FIELD" title="class or interface in java.text">MILLISECOND_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MINUTE_FIELD" title="class or interface in java.text">MINUTE_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#MONTH_FIELD" title="class or interface in java.text">MONTH_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#SECOND_FIELD" title="class or interface in java.text">SECOND_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#SHORT" title="class or interface in java.text">SHORT</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#TIMEZONE_FIELD" title="class or interface in java.text">TIMEZONE_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#WEEK_OF_MONTH_FIELD" title="class or interface in java.text">WEEK_OF_MONTH_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#WEEK_OF_YEAR_FIELD" title="class or interface in java.text">WEEK_OF_YEAR_FIELD</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#YEAR_FIELD" title="class or interface in java.text">YEAR_FIELD</a></code></li>\r
-</ul>\r
-</li>\r
-</ul>\r
-<!-- ======== CONSTRUCTOR SUMMARY ======== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="constructor_summary">\r
-<!-- -->\r
-</a>\r
-<h3>Constructor Summary</h3>\r
-<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Constructor Summary table, listing constructors, and an explanation">\r
-<caption><span>Constructors</span><span class="tabEnd"> </span></caption>\r
-<tr>\r
-<th class="colOne" scope="col">Constructor and Description</th>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat()">TmfTimestampFormat</a></strong>()</code>\r
-<div class="block">The default constructor (uses the default pattern)</div>\r
-</td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat(java.lang.String)">TmfTimestampFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code>\r
-<div class="block">The normal constructor</div>\r
-</td>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat(java.lang.String, java.util.TimeZone)">TmfTimestampFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern,\r
- <a href="http://download.oracle.com/javase/7/docs/api/java/util/TimeZone.html?is-external=true" title="class or interface in java.util">TimeZone</a> timeZone)</code>\r
-<div class="block">The full constructor</div>\r
-</td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colOne"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#TmfTimestampFormat(org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat)">TmfTimestampFormat</a></strong>(<a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> other)</code>\r
-<div class="block">The copy constructor</div>\r
-</td>\r
-</tr>\r
-</table>\r
-</li>\r
-</ul>\r
-<!-- ========== METHOD SUMMARY =========== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="method_summary">\r
-<!-- -->\r
-</a>\r
-<h3>Method Summary</h3>\r
-<table class="overviewSummary" border="0" cellpadding="3" cellspacing="0" summary="Method Summary table, listing methods, and an explanation">\r
-<caption><span>Methods</span><span class="tabEnd"> </span></caption>\r
-<tr>\r
-<th class="colFirst" scope="col">Modifier and Type</th>\r
-<th class="colLast" scope="col">Method and Description</th>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colFirst"><code>void</code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#applyPattern(java.lang.String)">applyPattern</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code> </td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><code><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#format(long)">format</a></strong>(long value)</code>\r
-<div class="block">Format the timestamp according to its pattern.</div>\r
-</td>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colFirst"><code>static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#getDefaulIntervalFormat()">getDefaulIntervalFormat</a></strong>()</code> </td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><code>static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#getDefaulTimeFormat()">getDefaulTimeFormat</a></strong>()</code> </td>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colFirst"><code>long</code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#parseValue(java.lang.String)">parseValue</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source)</code>\r
-<div class="block">Parse a string according to the format pattern</div>\r
-</td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><code>long</code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#parseValue(java.lang.String, long)">parseValue</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source,\r
- long ref)</code>\r
-<div class="block">Parse a string according to the format pattern</div>\r
-</td>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colFirst"><code>static void</code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultIntervalFormat(java.lang.String)">setDefaultIntervalFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code>\r
-<div class="block"><strong>Deprecated.</strong> \r
-<div class="block"><i>The default interval format pattern depends on the
- preferences, see <code>TmfTimePreferences</code>. To change the
- default time pattern, modify the preferences and call
- <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
-</div>\r
-</td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><code>static void</code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#setDefaultTimeFormat(java.lang.String)">setDefaultTimeFormat</a></strong>(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</code>\r
-<div class="block"><strong>Deprecated.</strong> \r
-<div class="block"><i>The default time pattern depends on the preferences, see
- <code>TmfTimePreferences</code>. To change the default time
- pattern, modify the preferences and call <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
-</div>\r
-</td>\r
-</tr>\r
-<tr class="altColor">\r
-<td class="colFirst"><code><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a></code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#toPattern()">toPattern</a></strong>()</code> </td>\r
-</tr>\r
-<tr class="rowColor">\r
-<td class="colFirst"><code>static void</code></td>\r
-<td class="colLast"><code><strong><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()">updateDefaultFormats</a></strong>()</code> </td>\r
-</tr>\r
-</table>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="methods_inherited_from_class_java.text.SimpleDateFormat">\r
-<!-- -->\r
-</a>\r
-<h3>Methods inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></h3>\r
-<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#applyLocalizedPattern(java.lang.String)" title="class or interface in java.text">applyLocalizedPattern</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#clone()" title="class or interface in java.text">clone</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#equals(java.lang.Object)" title="class or interface in java.text">equals</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#format(java.util.Date, java.lang.StringBuffer, java.text.FieldPosition)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#formatToCharacterIterator(java.lang.Object)" title="class or interface in java.text">formatToCharacterIterator</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#get2DigitYearStart()" title="class or interface in java.text">get2DigitYearStart</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#getDateFormatSymbols()" title="class or interface in java.text">getDateFormatSymbols</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#hashCode()" title="class or interface in java.text">hashCode</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#parse(java.lang.String, java.text.ParsePosition)" title="class or interface in java.text">parse</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#set2DigitYearStart(java.util.Date)" title="class or interface in java.text">set2DigitYearStart</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#setDateFormatSymbols(java.text.DateFormatSymbols)" title="class or interface in java.text">setDateFormatSymbols</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#toLocalizedPattern()" title="class or interface in java.text">toLocalizedPattern</a></code></li>\r
-</ul>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="methods_inherited_from_class_java.text.DateFormat">\r
-<!-- -->\r
-</a>\r
-<h3>Methods inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true" title="class or interface in java.text">DateFormat</a></h3>\r
-<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#format(java.util.Date)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#format(java.lang.Object, java.lang.StringBuffer, java.text.FieldPosition)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getAvailableLocales()" title="class or interface in java.text">getAvailableLocales</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getCalendar()" title="class or interface in java.text">getCalendar</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateInstance()" title="class or interface in java.text">getDateInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateInstance(int)" title="class or interface in java.text">getDateInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateInstance(int, java.util.Locale)" title="class or interface in java.text">getDateInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateTimeInstance()" title="class or interface in java.text">getDateTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateTimeInstance(int, int)" title="class or interface in java.text">getDateTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getDateTimeInstance(int, int, java.util.Locale)" title="class or interface in java.text">getDateTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getInstance()" title="class or interface in java.text">getInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getNumberFormat()" title="class or interface in java.text">getNumberFormat</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeInstance()" title="class or interface in java.text">getTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeInstance(int)" title="class or interface in java.text">getTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeInstance(int, java.util.Locale)" title="class or interface in java.text">getTimeInstance</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#getTimeZone()" title="class or interface in java.text">getTimeZone</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#isLenient()" title="class or interface in java.text">isLenient</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#parse(java.lang.String)" title="class or interface in java.text">parse</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#parseObject(java.lang.String, java.text.ParsePosition)" title="class or interface in java.text">parseObject</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setCalendar(java.util.Calendar)" title="class or interface in java.text">setCalendar</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setLenient(boolean)" title="class or interface in java.text">setLenient</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setNumberFormat(java.text.NumberFormat)" title="class or interface in java.text">setNumberFormat</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/DateFormat.html?is-external=true#setTimeZone(java.util.TimeZone)" title="class or interface in java.text">setTimeZone</a></code></li>\r
-</ul>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="methods_inherited_from_class_java.text.Format">\r
-<!-- -->\r
-</a>\r
-<h3>Methods inherited from class java.text.<a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true" title="class or interface in java.text">Format</a></h3>\r
-<code><a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true#format(java.lang.Object)" title="class or interface in java.text">format</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/text/Format.html?is-external=true#parseObject(java.lang.String)" title="class or interface in java.text">parseObject</a></code></li>\r
-</ul>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="methods_inherited_from_class_java.lang.Object">\r
-<!-- -->\r
-</a>\r
-<h3>Methods inherited from class java.lang.<a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true" title="class or interface in java.lang">Object</a></h3>\r
-<code><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#getClass()" title="class or interface in java.lang">getClass</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notify()" title="class or interface in java.lang">notify</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#notifyAll()" title="class or interface in java.lang">notifyAll</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#toString()" title="class or interface in java.lang">toString</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait()" title="class or interface in java.lang">wait</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long)" title="class or interface in java.lang">wait</a>, <a href="http://download.oracle.com/javase/7/docs/api/java/lang/Object.html?is-external=true#wait(long, int)" title="class or interface in java.lang">wait</a></code></li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</div>\r
-<div class="details">\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<!-- ============ FIELD DETAIL =========== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="field_detail">\r
-<!-- -->\r
-</a>\r
-<h3>Field Detail</h3>\r
-<a name="DEFAULT_TIME_PATTERN">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>DEFAULT_TIME_PATTERN</h4>\r
-<pre>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> DEFAULT_TIME_PATTERN</pre>\r
-<div class="block">The default timestamp pattern</div>\r
-<dl><dt><span class="strong">See Also:</span></dt><dd><a href="../../../../../../constant-values.html#org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_TIME_PATTERN">Constant Field Values</a></dd></dl>\r
-</li>\r
-</ul>\r
-<a name="DEFAULT_INTERVAL_PATTERN">\r
-<!-- -->\r
-</a>\r
-<ul class="blockListLast">\r
-<li class="blockList">\r
-<h4>DEFAULT_INTERVAL_PATTERN</h4>\r
-<pre>public static final <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> DEFAULT_INTERVAL_PATTERN</pre>\r
-<div class="block">The default interval pattern</div>\r
-<dl><dt><span class="strong">See Also:</span></dt><dd><a href="../../../../../../constant-values.html#org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat.DEFAULT_INTERVAL_PATTERN">Constant Field Values</a></dd></dl>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-<!-- ========= CONSTRUCTOR DETAIL ======== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="constructor_detail">\r
-<!-- -->\r
-</a>\r
-<h3>Constructor Detail</h3>\r
-<a name="TmfTimestampFormat()">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>TmfTimestampFormat</h4>\r
-<pre>public TmfTimestampFormat()</pre>\r
-<div class="block">The default constructor (uses the default pattern)</div>\r
-</li>\r
-</ul>\r
-<a name="TmfTimestampFormat(java.lang.String)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>TmfTimestampFormat</h4>\r
-<pre>public TmfTimestampFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
-<div class="block">The normal constructor</div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the format pattern</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="TmfTimestampFormat(java.lang.String, java.util.TimeZone)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>TmfTimestampFormat</h4>\r
-<pre>public TmfTimestampFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern,\r
- <a href="http://download.oracle.com/javase/7/docs/api/java/util/TimeZone.html?is-external=true" title="class or interface in java.util">TimeZone</a> timeZone)</pre>\r
-<div class="block">The full constructor</div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the format pattern</dd><dd><code>timeZone</code> - the time zone</dd><dt><span class="strong">Since:</span></dt>\r
- <dd>2.1</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="TmfTimestampFormat(org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockListLast">\r
-<li class="blockList">\r
-<h4>TmfTimestampFormat</h4>\r
-<pre>public TmfTimestampFormat(<a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> other)</pre>\r
-<div class="block">The copy constructor</div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>other</code> - the other format pattern</dd></dl>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-<!-- ============ METHOD DETAIL ========== -->\r
-<ul class="blockList">\r
-<li class="blockList"><a name="method_detail">\r
-<!-- -->\r
-</a>\r
-<h3>Method Detail</h3>\r
-<a name="updateDefaultFormats()">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>updateDefaultFormats</h4>\r
-<pre>public static void updateDefaultFormats()</pre>\r
-<dl><dt><span class="strong">Since:</span></dt>\r
- <dd>2.1</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="setDefaultTimeFormat(java.lang.String)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>setDefaultTimeFormat</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Deprecated.html?is-external=true" title="class or interface in java.lang">@Deprecated</a>\r
-public static void setDefaultTimeFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
-<div class="block"><span class="strong">Deprecated.</span> <i>The default time pattern depends on the preferences, see
- <code>TmfTimePreferences</code>. To change the default time
- pattern, modify the preferences and call <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the new default time pattern</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="getDefaulTimeFormat()">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>getDefaulTimeFormat</h4>\r
-<pre>public static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> getDefaulTimeFormat()</pre>\r
-<dl><dt><span class="strong">Returns:</span></dt><dd>the default time format pattern</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="setDefaultIntervalFormat(java.lang.String)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>setDefaultIntervalFormat</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/Deprecated.html?is-external=true" title="class or interface in java.lang">@Deprecated</a>\r
-public static void setDefaultIntervalFormat(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
-<div class="block"><span class="strong">Deprecated.</span> <i>The default interval format pattern depends on the
- preferences, see <code>TmfTimePreferences</code>. To change the
- default time pattern, modify the preferences and call
- <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html#updateDefaultFormats()"><code>updateDefaultFormats()</code></a></i></div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>pattern</code> - the new default interval pattern</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="getDefaulIntervalFormat()">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>getDefaulIntervalFormat</h4>\r
-<pre>public static <a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a> getDefaulIntervalFormat()</pre>\r
-<dl><dt><span class="strong">Returns:</span></dt><dd>the default interval format pattern</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="applyPattern(java.lang.String)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>applyPattern</h4>\r
-<pre>public void applyPattern(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> pattern)</pre>\r
-<dl>\r
-<dt><strong>Overrides:</strong></dt>\r
-<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#applyPattern(java.lang.String)" title="class or interface in java.text">applyPattern</a></code> in class <code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></code></dd>\r
-</dl>\r
-</li>\r
-</ul>\r
-<a name="toPattern()">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>toPattern</h4>\r
-<pre>public <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> toPattern()</pre>\r
-<dl>\r
-<dt><strong>Overrides:</strong></dt>\r
-<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true#toPattern()" title="class or interface in java.text">toPattern</a></code> in class <code><a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a></code></dd>\r
-</dl>\r
-</li>\r
-</ul>\r
-<a name="format(long)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>format</h4>\r
-<pre>public <a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> format(long value)</pre>\r
-<div class="block">Format the timestamp according to its pattern.</div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>value</code> - the timestamp value to format (in ns)</dd>\r
-<dt><span class="strong">Returns:</span></dt><dd>the formatted timestamp</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="parseValue(java.lang.String, long)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>parseValue</h4>\r
-<pre>public long parseValue(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source,\r
- long ref)\r
- throws <a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></pre>\r
-<div class="block">Parse a string according to the format pattern</div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>source</code> - the source string</dd><dd><code>ref</code> - the reference (base) time (in ns)</dd>\r
-<dt><span class="strong">Returns:</span></dt><dd>the parsed value (in ns)</dd>\r
-<dt><span class="strong">Throws:</span></dt>\r
-<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></code> - if the string has an invalid format</dd></dl>\r
-</li>\r
-</ul>\r
-<a name="parseValue(java.lang.String)">\r
-<!-- -->\r
-</a>\r
-<ul class="blockListLast">\r
-<li class="blockList">\r
-<h4>parseValue</h4>\r
-<pre>public long parseValue(<a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> source)\r
- throws <a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></pre>\r
-<div class="block">Parse a string according to the format pattern</div>\r
-<dl><dt><span class="strong">Parameters:</span></dt><dd><code>source</code> - the source string</dd>\r
-<dt><span class="strong">Returns:</span></dt><dd>the parsed value (in ns)</dd>\r
-<dt><span class="strong">Throws:</span></dt>\r
-<dd><code><a href="http://download.oracle.com/javase/7/docs/api/java/text/ParseException.html?is-external=true" title="class or interface in java.text">ParseException</a></code> - if the string has an invalid format</dd></dl>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</div>\r
-</div>\r
-<!-- ========= END OF CLASS DATA ========= -->\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>org.eclipse.linuxtools.tmf.core.timestamp</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<h1 class="bar"><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/package-summary.html" target="classFrame">org.eclipse.linuxtools.tmf.core.timestamp</a></h1>\r
-<div class="indexContainer">\r
-<h2 title="Classes">Classes</h2>\r
-<ul title="Classes">\r
-<li><a href="TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp" target="classFrame">TmfTimestampFormat</a></li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>org.eclipse.linuxtools.tmf.core.timestamp</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="../../../../../../stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<script type="text/javascript"><!--\r
- if (location.href.indexOf('is-external=true') == -1) {\r
- parent.document.title="org.eclipse.linuxtools.tmf.core.timestamp";\r
- }\r
-//-->\r
-</script>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<div class="header">\r
-<h1 title="Package" class="title">Package org.eclipse.linuxtools.tmf.core.timestamp</h1>\r
-</div>\r
-<div class="contentContainer">\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<table class="packageSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation">\r
-<caption><span>Class Summary</span><span class="tabEnd"> </span></caption>\r
-<tr>\r
-<th class="colFirst" scope="col">Class</th>\r
-<th class="colLast" scope="col">Description</th>\r
-</tr>\r
-<tbody>\r
-<tr class="altColor">\r
-<td class="colFirst"><a href="../../../../../../org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">TmfTimestampFormat</a></td>\r
-<td class="colLast">\r
-<div class="block">A formatting and parsing facility that can handle timestamps that span the
- epoch with a precision down to the nanosecond.</div>\r
-</td>\r
-</tr>\r
-</tbody>\r
-</table>\r
-</li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-org.eclipse.linuxtools.tmf.core.timestamp\r
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">\r
-<!-- NewPage -->\r
-<html lang="en">\r
-<head>\r
-<!-- Generated by javadoc (version 1.7.0_51) on Sat Feb 22 08:24:16 EST 2014 -->\r
-<title>Serialized Form</title>\r
-<meta name="date" content="2014-02-22">\r
-<link rel="stylesheet" type="text/css" href="stylesheet.css" title="Style">\r
-</head>\r
-<body>\r
-<script type="text/javascript"><!--\r
- if (location.href.indexOf('is-external=true') == -1) {\r
- parent.document.title="Serialized Form";\r
- }\r
-//-->\r
-</script>\r
-<noscript>\r
-<div>JavaScript is disabled on your browser.</div>\r
-</noscript>\r
-<div class="header">\r
-<h1 title="Serialized Form" class="title">Serialized Form</h1>\r
-</div>\r
-<div class="serializedFormContainer">\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h2 title="Package">Package org.eclipse.linuxtools.tmf.core.timestamp</h2>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat">\r
-<!-- -->\r
-</a>\r
-<h3>Class <a href="org/eclipse/linuxtools/tmf/core/timestamp/TmfTimestampFormat.html" title="class in org.eclipse.linuxtools.tmf.core.timestamp">org.eclipse.linuxtools.tmf.core.timestamp.TmfTimestampFormat</a> extends <a href="http://download.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html?is-external=true" title="class or interface in java.text">SimpleDateFormat</a> implements Serializable</h3>\r
-<dl class="nameValue">\r
-<dt>serialVersionUID:</dt>\r
-<dd>2835829763122454020L</dd>\r
-</dl>\r
-<ul class="blockList">\r
-<li class="blockList"><a name="serializedForm">\r
-<!-- -->\r
-</a>\r
-<h3>Serialized Fields</h3>\r
-<ul class="blockList">\r
-<li class="blockList">\r
-<h4>fPattern</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fPattern</pre>\r
-</li>\r
-<li class="blockList">\r
-<h4>fPatternDecimalSeparatorIndex</h4>\r
-<pre>int fPatternDecimalSeparatorIndex</pre>\r
-</li>\r
-<li class="blockList">\r
-<h4>fDecimalSeparator</h4>\r
-<pre>char fDecimalSeparator</pre>\r
-</li>\r
-<li class="blockList">\r
-<h4>fDateTimePattern</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fDateTimePattern</pre>\r
-</li>\r
-<li class="blockList">\r
-<h4>fSubSecPattern</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fSubSecPattern</pre>\r
-</li>\r
-<li class="blockList">\r
-<h4>fSupplPatterns</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/util/List.html?is-external=true" title="class or interface in java.util">List</a><<a href="http://download.oracle.com/javase/7/docs/api/java/util/List.html?is-external=true" title="class or interface in java.util">E</a>> fSupplPatterns</pre>\r
-</li>\r
-<li class="blockList">\r
-<h4>fSupplPatternLetters</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fSupplPatternLetters</pre>\r
-<div class="block">The supplementary pattern letters. Can be redefined by sub-classes
- to either override existing letters or augment the letter set.
- If so, the format() method must provide the (re-)implementation of the
- pattern.</div>\r
-</li>\r
-<li class="blockList">\r
-<h4>fSubSecPatternChars</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fSubSecPatternChars</pre>\r
-<div class="block">The sub-second pattern letters.</div>\r
-<dl><dt><span class="strong">Since:</span></dt>\r
- <dd>3.0</dd></dl>\r
-</li>\r
-<li class="blockList">\r
-<h4>fDelimiterChars</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fDelimiterChars</pre>\r
-<div class="block">The optional sub-second delimiter characters.</div>\r
-<dl><dt><span class="strong">Since:</span></dt>\r
- <dd>3.0</dd></dl>\r
-</li>\r
-<li class="blockList">\r
-<h4>fOpenBracket</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fOpenBracket</pre>\r
-<div class="block">The open bracket symbol</div>\r
-</li>\r
-<li class="blockListLast">\r
-<h4>fCloseBracket</h4>\r
-<pre><a href="http://download.oracle.com/javase/7/docs/api/java/lang/String.html?is-external=true" title="class or interface in java.lang">String</a> fCloseBracket</pre>\r
-<div class="block">The closing bracket symbol</div>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</li>\r
-</ul>\r
-</div>\r
-</body>\r
-</html>\r
+++ /dev/null
-/* Javadoc style sheet */\r
-/*\r
-Overall document style\r
-*/\r
-body {\r
- background-color:#ffffff;\r
- color:#353833;\r
- font-family:Arial, Helvetica, sans-serif;\r
- font-size:76%;\r
- margin:0;\r
-}\r
-a:link, a:visited {\r
- text-decoration:none;\r
- color:#4c6b87;\r
-}\r
-a:hover, a:focus {\r
- text-decoration:none;\r
- color:#bb7a2a;\r
-}\r
-a:active {\r
- text-decoration:none;\r
- color:#4c6b87;\r
-}\r
-a[name] {\r
- color:#353833;\r
-}\r
-a[name]:hover {\r
- text-decoration:none;\r
- color:#353833;\r
-}\r
-pre {\r
- font-size:1.3em;\r
-}\r
-h1 {\r
- font-size:1.8em;\r
-}\r
-h2 {\r
- font-size:1.5em;\r
-}\r
-h3 {\r
- font-size:1.4em;\r
-}\r
-h4 {\r
- font-size:1.3em;\r
-}\r
-h5 {\r
- font-size:1.2em;\r
-}\r
-h6 {\r
- font-size:1.1em;\r
-}\r
-ul {\r
- list-style-type:disc;\r
-}\r
-code, tt {\r
- font-size:1.2em;\r
-}\r
-dt code {\r
- font-size:1.2em;\r
-}\r
-table tr td dt code {\r
- font-size:1.2em;\r
- vertical-align:top;\r
-}\r
-sup {\r
- font-size:.6em;\r
-}\r
-/*\r
-Document title and Copyright styles\r
-*/\r
-.clear {\r
- clear:both;\r
- height:0px;\r
- overflow:hidden;\r
-}\r
-.aboutLanguage {\r
- float:right;\r
- padding:0px 21px;\r
- font-size:.8em;\r
- z-index:200;\r
- margin-top:-7px;\r
-}\r
-.legalCopy {\r
- margin-left:.5em;\r
-}\r
-.bar a, .bar a:link, .bar a:visited, .bar a:active {\r
- color:#FFFFFF;\r
- text-decoration:none;\r
-}\r
-.bar a:hover, .bar a:focus {\r
- color:#bb7a2a;\r
-}\r
-.tab {\r
- background-color:#0066FF;\r
- background-image:url(resources/titlebar.gif);\r
- background-position:left top;\r
- background-repeat:no-repeat;\r
- color:#ffffff;\r
- padding:8px;\r
- width:5em;\r
- font-weight:bold;\r
-}\r
-/*\r
-Navigation bar styles\r
-*/\r
-.bar {\r
- background-image:url(resources/background.gif);\r
- background-repeat:repeat-x;\r
- color:#FFFFFF;\r
- padding:.8em .5em .4em .8em;\r
- height:auto;/*height:1.8em;*/\r
- font-size:1em;\r
- margin:0;\r
-}\r
-.topNav {\r
- background-image:url(resources/background.gif);\r
- background-repeat:repeat-x;\r
- color:#FFFFFF;\r
- float:left;\r
- padding:0;\r
- width:100%;\r
- clear:right;\r
- height:2.8em;\r
- padding-top:10px;\r
- overflow:hidden;\r
-}\r
-.bottomNav {\r
- margin-top:10px;\r
- background-image:url(resources/background.gif);\r
- background-repeat:repeat-x;\r
- color:#FFFFFF;\r
- float:left;\r
- padding:0;\r
- width:100%;\r
- clear:right;\r
- height:2.8em;\r
- padding-top:10px;\r
- overflow:hidden;\r
-}\r
-.subNav {\r
- background-color:#dee3e9;\r
- border-bottom:1px solid #9eadc0;\r
- float:left;\r
- width:100%;\r
- overflow:hidden;\r
-}\r
-.subNav div {\r
- clear:left;\r
- float:left;\r
- padding:0 0 5px 6px;\r
-}\r
-ul.navList, ul.subNavList {\r
- float:left;\r
- margin:0 25px 0 0;\r
- padding:0;\r
-}\r
-ul.navList li{\r
- list-style:none;\r
- float:left;\r
- padding:3px 6px;\r
-}\r
-ul.subNavList li{\r
- list-style:none;\r
- float:left;\r
- font-size:90%;\r
-}\r
-.topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited {\r
- color:#FFFFFF;\r
- text-decoration:none;\r
-}\r
-.topNav a:hover, .bottomNav a:hover {\r
- text-decoration:none;\r
- color:#bb7a2a;\r
-}\r
-.navBarCell1Rev {\r
- background-image:url(resources/tab.gif);\r
- background-color:#a88834;\r
- color:#FFFFFF;\r
- margin: auto 5px;\r
- border:1px solid #c9aa44;\r
-}\r
-/*\r
-Page header and footer styles\r
-*/\r
-.header, .footer {\r
- clear:both;\r
- margin:0 20px;\r
- padding:5px 0 0 0;\r
-}\r
-.indexHeader {\r
- margin:10px;\r
- position:relative;\r
-}\r
-.indexHeader h1 {\r
- font-size:1.3em;\r
-}\r
-.title {\r
- color:#2c4557;\r
- margin:10px 0;\r
-}\r
-.subTitle {\r
- margin:5px 0 0 0;\r
-}\r
-.header ul {\r
- margin:0 0 25px 0;\r
- padding:0;\r
-}\r
-.footer ul {\r
- margin:20px 0 5px 0;\r
-}\r
-.header ul li, .footer ul li {\r
- list-style:none;\r
- font-size:1.2em;\r
-}\r
-/*\r
-Heading styles\r
-*/\r
-div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 {\r
- background-color:#dee3e9;\r
- border-top:1px solid #9eadc0;\r
- border-bottom:1px solid #9eadc0;\r
- margin:0 0 6px -8px;\r
- padding:2px 5px;\r
-}\r
-ul.blockList ul.blockList ul.blockList li.blockList h3 {\r
- background-color:#dee3e9;\r
- border-top:1px solid #9eadc0;\r
- border-bottom:1px solid #9eadc0;\r
- margin:0 0 6px -8px;\r
- padding:2px 5px;\r
-}\r
-ul.blockList ul.blockList li.blockList h3 {\r
- padding:0;\r
- margin:15px 0;\r
-}\r
-ul.blockList li.blockList h2 {\r
- padding:0px 0 20px 0;\r
-}\r
-/*\r
-Page layout container styles\r
-*/\r
-.contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer {\r
- clear:both;\r
- padding:10px 20px;\r
- position:relative;\r
-}\r
-.indexContainer {\r
- margin:10px;\r
- position:relative;\r
- font-size:1.0em;\r
-}\r
-.indexContainer h2 {\r
- font-size:1.1em;\r
- padding:0 0 3px 0;\r
-}\r
-.indexContainer ul {\r
- margin:0;\r
- padding:0;\r
-}\r
-.indexContainer ul li {\r
- list-style:none;\r
-}\r
-.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt {\r
- font-size:1.1em;\r
- font-weight:bold;\r
- margin:10px 0 0 0;\r
- color:#4E4E4E;\r
-}\r
-.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd {\r
- margin:10px 0 10px 20px;\r
-}\r
-.serializedFormContainer dl.nameValue dt {\r
- margin-left:1px;\r
- font-size:1.1em;\r
- display:inline;\r
- font-weight:bold;\r
-}\r
-.serializedFormContainer dl.nameValue dd {\r
- margin:0 0 0 1px;\r
- font-size:1.1em;\r
- display:inline;\r
-}\r
-/*\r
-List styles\r
-*/\r
-ul.horizontal li {\r
- display:inline;\r
- font-size:0.9em;\r
-}\r
-ul.inheritance {\r
- margin:0;\r
- padding:0;\r
-}\r
-ul.inheritance li {\r
- display:inline;\r
- list-style:none;\r
-}\r
-ul.inheritance li ul.inheritance {\r
- margin-left:15px;\r
- padding-left:15px;\r
- padding-top:1px;\r
-}\r
-ul.blockList, ul.blockListLast {\r
- margin:10px 0 10px 0;\r
- padding:0;\r
-}\r
-ul.blockList li.blockList, ul.blockListLast li.blockList {\r
- list-style:none;\r
- margin-bottom:25px;\r
-}\r
-ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList {\r
- padding:0px 20px 5px 10px;\r
- border:1px solid #9eadc0;\r
- background-color:#f9f9f9;\r
-}\r
-ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList {\r
- padding:0 0 5px 8px;\r
- background-color:#ffffff;\r
- border:1px solid #9eadc0;\r
- border-top:none;\r
-}\r
-ul.blockList ul.blockList ul.blockList ul.blockList li.blockList {\r
- margin-left:0;\r
- padding-left:0;\r
- padding-bottom:15px;\r
- border:none;\r
- border-bottom:1px solid #9eadc0;\r
-}\r
-ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast {\r
- list-style:none;\r
- border-bottom:none;\r
- padding-bottom:0;\r
-}\r
-table tr td dl, table tr td dl dt, table tr td dl dd {\r
- margin-top:0;\r
- margin-bottom:1px;\r
-}\r
-/*\r
-Table styles\r
-*/\r
-.contentContainer table, .classUseContainer table, .constantValuesContainer table {\r
- border-bottom:1px solid #9eadc0;\r
- width:100%;\r
-}\r
-.contentContainer ul li table, .classUseContainer ul li table, .constantValuesContainer ul li table {\r
- width:100%;\r
-}\r
-.contentContainer .description table, .contentContainer .details table {\r
- border-bottom:none;\r
-}\r
-.contentContainer ul li table th.colOne, .contentContainer ul li table th.colFirst, .contentContainer ul li table th.colLast, .classUseContainer ul li table th, .constantValuesContainer ul li table th, .contentContainer ul li table td.colOne, .contentContainer ul li table td.colFirst, .contentContainer ul li table td.colLast, .classUseContainer ul li table td, .constantValuesContainer ul li table td{\r
- vertical-align:top;\r
- padding-right:20px;\r
-}\r
-.contentContainer ul li table th.colLast, .classUseContainer ul li table th.colLast,.constantValuesContainer ul li table th.colLast,\r
-.contentContainer ul li table td.colLast, .classUseContainer ul li table td.colLast,.constantValuesContainer ul li table td.colLast,\r
-.contentContainer ul li table th.colOne, .classUseContainer ul li table th.colOne,\r
-.contentContainer ul li table td.colOne, .classUseContainer ul li table td.colOne {\r
- padding-right:3px;\r
-}\r
-.overviewSummary caption, .packageSummary caption, .contentContainer ul.blockList li.blockList caption, .summary caption, .classUseContainer caption, .constantValuesContainer caption {\r
- position:relative;\r
- text-align:left;\r
- background-repeat:no-repeat;\r
- color:#FFFFFF;\r
- font-weight:bold;\r
- clear:none;\r
- overflow:hidden;\r
- padding:0px;\r
- margin:0px;\r
-}\r
-caption a:link, caption a:hover, caption a:active, caption a:visited {\r
- color:#FFFFFF;\r
-}\r
-.overviewSummary caption span, .packageSummary caption span, .contentContainer ul.blockList li.blockList caption span, .summary caption span, .classUseContainer caption span, .constantValuesContainer caption span {\r
- white-space:nowrap;\r
- padding-top:8px;\r
- padding-left:8px;\r
- display:block;\r
- float:left;\r
- background-image:url(resources/titlebar.gif);\r
- height:18px;\r
-}\r
-.overviewSummary .tabEnd, .packageSummary .tabEnd, .contentContainer ul.blockList li.blockList .tabEnd, .summary .tabEnd, .classUseContainer .tabEnd, .constantValuesContainer .tabEnd {\r
- width:10px;\r
- background-image:url(resources/titlebar_end.gif);\r
- background-repeat:no-repeat;\r
- background-position:top right;\r
- position:relative;\r
- float:left;\r
-}\r
-ul.blockList ul.blockList li.blockList table {\r
- margin:0 0 12px 0px;\r
- width:100%;\r
-}\r
-.tableSubHeadingColor {\r
- background-color: #EEEEFF;\r
-}\r
-.altColor {\r
- background-color:#eeeeef;\r
-}\r
-.rowColor {\r
- background-color:#ffffff;\r
-}\r
-.overviewSummary td, .packageSummary td, .contentContainer ul.blockList li.blockList td, .summary td, .classUseContainer td, .constantValuesContainer td {\r
- text-align:left;\r
- padding:3px 3px 3px 7px;\r
-}\r
-th.colFirst, th.colLast, th.colOne, .constantValuesContainer th {\r
- background:#dee3e9;\r
- border-top:1px solid #9eadc0;\r
- border-bottom:1px solid #9eadc0;\r
- text-align:left;\r
- padding:3px 3px 3px 7px;\r
-}\r
-td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover {\r
- font-weight:bold;\r
-}\r
-td.colFirst, th.colFirst {\r
- border-left:1px solid #9eadc0;\r
- white-space:nowrap;\r
-}\r
-td.colLast, th.colLast {\r
- border-right:1px solid #9eadc0;\r
-}\r
-td.colOne, th.colOne {\r
- border-right:1px solid #9eadc0;\r
- border-left:1px solid #9eadc0;\r
-}\r
-table.overviewSummary {\r
- padding:0px;\r
- margin-left:0px;\r
-}\r
-table.overviewSummary td.colFirst, table.overviewSummary th.colFirst,\r
-table.overviewSummary td.colOne, table.overviewSummary th.colOne {\r
- width:25%;\r
- vertical-align:middle;\r
-}\r
-table.packageSummary td.colFirst, table.overviewSummary th.colFirst {\r
- width:25%;\r
- vertical-align:middle;\r
-}\r
-/*\r
-Content styles\r
-*/\r
-.description pre {\r
- margin-top:0;\r
-}\r
-.deprecatedContent {\r
- margin:0;\r
- padding:10px 0;\r
-}\r
-.docSummary {\r
- padding:0;\r
-}\r
-/*\r
-Formatting effect styles\r
-*/\r
-.sourceLineNo {\r
- color:green;\r
- padding:0 30px 0 0;\r
-}\r
-h1.hidden {\r
- visibility:hidden;\r
- overflow:hidden;\r
- font-size:.9em;\r
-}\r
-.block {\r
- display:block;\r
- margin:3px 0 0 0;\r
-}\r
-.strong {\r
- font-weight:bold;\r
-}\r
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.help"
+ id="org.eclipse.tracecompass.doc.user"
download-size="0"
install-size="0"
version="0.0.0"/>
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.help"
+ id="org.eclipse.tracecompass.doc.user"
download-size="0"
install-size="0"
version="0.0.0"/>
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.help"
+ id="org.eclipse.tracecompass.doc.user"
download-size="0"
install-size="0"
version="0.0.0"/>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
-<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
-<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
-<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.rcp.help" type="4"/> </resources>}"/>
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/>
-<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.rcp.help"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.rcp.help/build.xml}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-</launchConfiguration>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
- <name>org.eclipse.tracecompass.rcp.help</name>
- <comment></comment>
- <projects>
- </projects>
- <buildSpec>
- <buildCommand>
- <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
- <triggers>clean,full,incremental,</triggers>
- <arguments>
- <dictionary>
- <key>LaunchConfigHandle</key>
- <value><project>/.externalToolBuilders/RCP Help Builder.launch</value>
- </dictionary>
- <dictionary>
- <key>incclean</key>
- <value>true</value>
- </dictionary>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.ManifestBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.SchemaBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- </buildSpec>
- <natures>
- <nature>org.eclipse.pde.PluginNature</nature>
- </natures>
-</projectDescription>
+++ /dev/null
-eclipse.preferences.version=1
-encoding/<project>=UTF-8
+++ /dev/null
-eclipse.preferences.version=1
-line.separator=\n
+++ /dev/null
-Manifest-Version: 1.0
-Bundle-ManifestVersion: 2
-Bundle-Name: %Bundle-Name
-Bundle-Vendor: %Bundle-Vendor
-Bundle-Version: 0.1.0.qualifier
-Bundle-Localization: plugin
-Bundle-SymbolicName: org.eclipse.tracecompass.rcp.help;singleton:=true
-Require-Bundle: org.eclipse.help
+++ /dev/null
-This describes how to build the documentation found in the o.e.t.tracing.rcp.help
-plugin.
-
-
-Your Eclipse environment first needs to have the "Mylyn Wikitext" plugin
-installed. It can be found in the default Eclipse repository, under
-"Collaboration".
-
-Once that is installed, you should be able to use the manual Eclipse builder to
-generate the doc : select the tracing.rcp.help plugin and choose, in the top-menu,
-"Project -> Build Project".
-
-It uses the build.xml Ant script, but it's recommended to run it from within
-Eclipse, since the builder will pass some environment variables that the script
-needs.
-
-You might get a warning from build.properties because of a missing file. This
-file gets generated with the rest of the doc, so once you have run these steps
-(and refreshed the project if needed), the warning should disappear.
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
-<title>About</title>
-</head>
-<body lang="EN-US">
-<h2>About This Content</h2>
-
-<p>June 5, 2006</p>
-<h3>License</h3>
-
-<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
-indicated below, the Content is provided to you under the terms and conditions of the
-Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
-at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
-For purposes of the EPL, "Program" will mean the Content.</p>
-
-<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
-being redistributed by another party ("Redistributor") and different terms and conditions may
-apply to your use of any object code in the Content. Check the Redistributor's license that was
-provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
-indicated below, the terms and conditions of the EPL still apply to any source code in the Content
-and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
-
-</body>
-</html>
\ No newline at end of file
+++ /dev/null
-/* following font face declarations need to be removed for DBCS */
-
-
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
-pre { font-family: Courier, monospace}
-
-/* end font face declarations */
-
-/* following font size declarations should be OK for DBCS */
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
-pre { font-size: 12pt}
-
-/* end font size declarations */
-
-body { background: #FFFFFF}
-h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
-h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
-h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
-h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
-h5 { font size: 13.5pt; }
-p { font-size: 12pt; }
-pre { margin-left: 6; font-size: 9pt }
-
-a:link { color: #006699 }
-a:visited { color: #996699 }
-a:hover { color: #006699 }
-
-ul { margin-top: 0; margin-bottom: 10 }
-li { margin-top: 0; margin-bottom: 0 }
-li p { margin-top: 0; margin-bottom: 0 }
-ol { margin-top: 0; margin-bottom: 10 }
-dl { margin-top: 0; margin-bottom: 10 }
-dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
-dd { margin-top: 0; margin-bottom: 0 }
-strong { font-weight: bold}
-em { font-style: italic}
-var { font-style: italic}
-div.revision { border-left-style: solid; border-left-width: thin;
- border-left-color: #7B68EE; padding-left:5 }
-th { font-weight: bold }
-.hidden {
- display: none;
-}
-
-/* Mike Behm's addition to the style sheet */
-.userinput { font-family: monospace; }
-.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
-.notetitle {
- color: #000000;
- font-family: helvetica, arial, sans-serif;
- font-weight: bold;
- }
-div.linux {display:none;}
-.firsterm {font-style:italic;}
-
-.typewriter {font-family:monospace;}
-.bold {font-weight:600;}
-.linethrough {text-decoration: line-through;}
-.underline {text-decoration: underline;}
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-bin.includes = plugin.xml,\
- META-INF/,\
- about.html,\
- plugin.properties,\
- book.css,\
- doc/
-jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
- platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
-src.includes = about.html
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="org.eclipse.linuxtools.tracing.rcp.help" default="build">
- <description>
- Generate Eclipse help content for the Linux Tools Trace Viewer user guide
- </description>
-
- <!-- Set correct values -->
- <property name="help.doc.url.base" value="http://wiki.eclipse.org" />
- <property name="ug.path" value="Linux_Tools_Project/Trace_Viewer/User_Guide" />
- <property name="ug.title" value="Trace Compass RCP User Guide" />
-
- <path id="wikitext.tasks.classpath">
- <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
- <fileset dir="${osgi.syspath}" erroronmissingdir="false">
- <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
- <include name="com.google.guava_*.jar" />
- </fileset>
-
- <!-- For Maven builds: use the compile_classpath -->
- <pathelement path="${compile_classpath}" />
- </path>
-
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
- <!-- Different location in more recent versions of Mylyn (Luna ?) -->
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
-
- <target name="build" description="Generate Eclipse help content for the Trace Compass RCP User Guide">
- <wikitext-to-eclipse-help markupLanguage="MediaWiki"
- validate="true"
- failonvalidationerror="true"
- overwrite="true"
- multipleOutputFiles="true"
- navigationimages="true"
- title="${ug.title}"
- formatoutput="true"
- helpPrefix="doc">
- <fileset dir="./doc">
- <include name="User-Guide.mediawiki" />
- </fileset>
- <stylesheet url="book.css" />
- </wikitext-to-eclipse-help>
- <antcall target="test" />
- </target>
-
- <target name="test" description="Verify that all of the HTML files are well-formed XML">
- <!--
- Don't bother with DTD validation: we only care if the files are well-formed.
- We therefore provide an empty DTD
- -->
- <xmlvalidate lenient="true">
- <fileset dir="doc">
- <include name="**/*.html" />
- </fileset>
- <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
- </xmlvalidate>
- </target>
-
-
- <!-- If you need a proxy for the "download" target, set it here -->
- <!--
- <setproxy proxyhost="host" proxyport="port"/>
- -->
-
- <target name="download" description="Download the current contents of the LTTng User Guide from the Eclipse wiki">
- <mediawiki-to-eclipse-help wikiBaseUrl="${help.doc.url.base}" title="${ug.title}" formatoutput="true" dest="." templateExcludes="*eclipseproject*">
- <path name="${ug.path}" title="${ug.title}" generateToc="false" />
- <stylesheet url="book.css" />
- <pageAppendum>
-= Updating This Document =
-
-This document is maintained in a collaborative wiki. If you wish to update or modify this document please visit
-http://wiki.eclipse.org/Linux_Tools_Project/LTTng2/User_Guide.
- </pageAppendum>
- </mediawiki-to-eclipse-help>
- </target>
-
- <target name ="clean" description="Delete all generated files">
- <delete failonerror="false" includeemptydirs="true">
- <!-- Files under doc/ (generated locally) -->
- <fileset dir="doc" includes="**/*.html" />
- <fileset dir="doc" includes="**/*.xml" />
-
- <!-- Files downloaded from the Eclipse wiki -->
- <fileset dir="Linux_Tools_Project" />
- <fileset file="toc.xml" />
- </delete>
- </target>
-
-</project>
+++ /dev/null
-*.html
-*.xml
+++ /dev/null
-= Overview =
-The Trace Compass RCP version is a stand-alone application based on Eclipse's
-Rich Client Platform (RCP). The purpose of this is to provide a lightweight
-application to view and analyze traces. It includes most standard features found
-in the Trace Compass project.
-
-= Getting Started =
-To start the Trace Compass RCP, go to the directory where it is installed and
-then run the executable named '''tracecompass'''. During startup, the program
-will create, if necessary, an Eclipse workspace under the user's home directory
-with the name ''.tracecompass''. It also creates, if needed, a default tracing
-project called ''Tracing''.
-
-Now the application can be used as described in the regular User Guide. (see
-section [[#References | References]]).
-
-= Updating the application =
-The RCP is pre-configured to point to the update site of its release "track".
-For example, if you download a "nightly" RCP, it will update using that
-"nightly" update site. These settings are configurable in the preferences, but
-in most cases, the user should not have to change them.
-
-The program does not check automatically for updates. To check manually, you can
-click on '''Help''' -> '''Check for Updates'''. If updates are available, a
-standard Eclipse update dialog will offer their installation.
-
-= Opening a Trace =
-To open a trace, click on the '''File''' menu and select '''Open Trace...'''.
-A new dialog will show up for selecting a trace to open. Select a trace file
-and then click on '''OK'''. Note that for traces that are directories
-(such as Common Trace Format (CTF) traces) any file in the trace directory can
-be selected to open the trace. The auto detection algorithm will then validate
-the trace against all known trace types. If multiple trace types are valid, a
-trace type is chosen based on a confidence criteria. The validation process and
-the computation of the confidence level are trace type specific. After
-successful validation, the trace will be opened with the detected trace type.
-
-Alternatively the user can launch '''tracecompass''' with the command-line
-argument '''--open <trace-path>'''. The trace will then automatically open
-using the same algorithm than described above.
-
-In both of the above cases, the trace will be linked to the default project.
-
-= References =
-
-* [http://www.eclipse.org/tracecompass Trace Compass project]
-* [http://www.lttng.org/ LTTng project]
-
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Bernd Hufmann - Initial API and implementation
-###############################################################################
-
-Bundle-Vendor = Eclipse Trace Compass
-Bundle-Name = Trace Compass RCP Help Plug-in
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<plugin>
-<!-- This part should be in a documentation plugin -->
-<!-- Configure the help contribution for this plugin -->
- <extension point="org.eclipse.help.toc">
- <toc
- file="doc/User-Guide-toc.xml"
- primary="true" />
- </extension>
-</plugin>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (C) 2011, Red Hat, Inc.
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <artifactId>org.eclipse.tracecompass</artifactId>
- <groupId>org.eclipse.tracecompass</groupId>
- <version>0.1.0-SNAPSHOT</version>
- </parent>
-
- <artifactId>org.eclipse.tracecompass.rcp.help</artifactId>
- <version>0.1.0-SNAPSHOT</version>
- <packaging>eclipse-plugin</packaging>
-
- <name>Trace Compass RCP Help Plug-in</name>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-antrun-plugin</artifactId>
- <executions>
- <execution>
- <id>generate-documentation</id>
- <phase>generate-sources</phase>
- <configuration>
- <echo>Generating Trace Viewer Help Files</echo>
- <target>
- <property name="compile_classpath" refid="maven.compile.classpath" />
- <ant target="build" inheritRefs="true" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- <execution>
- <id>clean-documentation</id>
- <phase>clean</phase>
- <configuration>
- <echo>Cleaning up generated Trace Viewer Help Files</echo>
- <target>
- <ant target="clean" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- </executions>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-launcher</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-nodeps</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- </dependencies>
- </plugin>
- </plugins>
- </build>
-
- <groupId>org.eclipse.tracecompass</groupId>
-</project>
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.rcp.help"
+ id="org.eclipse.tracecompass.rcp.doc.user"
download-size="0"
install-size="0"
version="0.0.0"
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
-<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
-<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
-<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.tmf.help" type="4"/> </resources>}"/>
-<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS">
-<listEntry value="/org.eclipse.tracecompass.tmf.help/build.xml"/>
-</listAttribute>
-<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES">
-<listEntry value="1"/>
-</listAttribute>
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.tmf.help"/>
-<stringAttribute key="org.eclipse.jdt.launching.SOURCE_PATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.tmf.help/build.xml}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-<stringAttribute key="process_factory_id" value="org.eclipse.ant.ui.remoteAntProcessFactory"/>
-</launchConfiguration>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
- <name>org.eclipse.tracecompass.tmf.help</name>
- <comment></comment>
- <projects>
- </projects>
- <buildSpec>
- <buildCommand>
- <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
- <triggers>clean,full,incremental,</triggers>
- <arguments>
- <dictionary>
- <key>LaunchConfigHandle</key>
- <value><project>/.externalToolBuilders/org.eclipse.linuxtools.tmf.help build.xml [Builder].launch</value>
- </dictionary>
- <dictionary>
- <key>incclean</key>
- <value>true</value>
- </dictionary>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.ManifestBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.SchemaBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- </buildSpec>
- <natures>
- <nature>org.eclipse.pde.PluginNature</nature>
- <nature>org.eclipse.mylyn.wikitext.ui.wikiTextNature</nature>
- </natures>
-</projectDescription>
+++ /dev/null
-eclipse.preferences.version=1
-encoding/<project>=UTF-8
+++ /dev/null
-eclipse.preferences.version=1
-line.separator=\n
+++ /dev/null
-eclipse.preferences.version=1
-org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false
+++ /dev/null
-Manifest-Version: 1.0
-Bundle-ManifestVersion: 2
-Bundle-Name: %Bundle-Name
-Bundle-Vendor: %Bundle-Vendor
-Bundle-Version: 0.1.0.qualifier
-Bundle-Localization: plugin
-Bundle-SymbolicName: org.eclipse.tracecompass.tmf.help;singleton:=true
-Require-Bundle: org.eclipse.help
+++ /dev/null
-This describes how to build the documentation found in the o.e.t.tmf.help
-plugin.
-
-
-Your Eclipse environment first needs to have the "Mylyn Wikitext" plugin
-installed. It can be found in the default Eclipse repository, under
-"Collaboration".
-
-Once that is installed, you should be able to use the manual Eclipse builder to
-generate the doc : select the tmf.help plugin and choose, in the top-menu,
-"Project -> Build Project".
-
-It uses the build.xml Ant script, but it's recommended to run it from within
-Eclipse, since the builder will pass some environment variables that the script
-needs.
-
-You might get a warning from build.properties because of a missing file. This
-file gets generated with the rest of the doc, so once you have run these steps
-(and refreshed the project if needed), the warning should disappear.
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
-<title>About</title>
-</head>
-<body lang="EN-US">
-<h2>About This Content</h2>
-
-<p>June 5, 2006</p>
-<h3>License</h3>
-
-<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
-indicated below, the Content is provided to you under the terms and conditions of the
-Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
-at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
-For purposes of the EPL, "Program" will mean the Content.</p>
-
-<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
-being redistributed by another party ("Redistributor") and different terms and conditions may
-apply to your use of any object code in the Content. Check the Redistributor's license that was
-provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
-indicated below, the terms and conditions of the EPL still apply to any source code in the Content
-and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
-
-</body>
-</html>
\ No newline at end of file
+++ /dev/null
-/* following font face declarations need to be removed for DBCS */
-
-
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
-pre { font-family: Courier, monospace}
-
-/* end font face declarations */
-
-/* following font size declarations should be OK for DBCS */
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
-pre { font-size: 12pt}
-
-/* end font size declarations */
-
-body { background: #FFFFFF}
-h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
-h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
-h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
-h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
-h5 { font size: 13.5pt; }
-p { font-size: 12pt; }
-pre { margin-left: 6; font-size: 9pt }
-
-a:link { color: #006699 }
-a:visited { color: #996699 }
-a:hover { color: #006699 }
-
-ul { margin-top: 0; margin-bottom: 10 }
-li { margin-top: 0; margin-bottom: 0 }
-li p { margin-top: 0; margin-bottom: 0 }
-ol { margin-top: 0; margin-bottom: 10 }
-dl { margin-top: 0; margin-bottom: 10 }
-dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
-dd { margin-top: 0; margin-bottom: 0 }
-strong { font-weight: bold}
-em { font-style: italic}
-var { font-style: italic}
-div.revision { border-left-style: solid; border-left-width: thin;
- border-left-color: #7B68EE; padding-left:5 }
-th { font-weight: bold }
-.hidden {
- display: none;
-}
-
-/* Mike Behm's addition to the style sheet */
-.userinput { font-family: monospace; }
-.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
-.notetitle {
- color: #000000;
- font-family: helvetica, arial, sans-serif;
- font-weight: bold;
- }
-div.linux {display:none;}
-.firsterm {font-style:italic;}
-
-.typewriter {font-family:monospace;}
-.bold {font-weight:600;}
-.linethrough {text-decoration: line-through;}
-.underline {text-decoration: underline;}
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-bin.includes = plugin.xml,\
- META-INF/,\
- about.html,\
- plugin.properties,\
- book.css,\
- doc/
-jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
- platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
-src.includes = about.html
-
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="org.eclipse.linuxtools.tmf.help" default="build" basedir=".">
- <description>
- Generate Eclipse help content for the Linux Tools TMF Developer Guide
- </description>
-
- <property name="ug.title" value="TMF Developer Guide" />
-
- <path id="wikitext.tasks.classpath">
- <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
- <fileset dir="${osgi.syspath}" erroronmissingdir="false">
- <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
- <include name="com.google.guava_*.jar" />
- </fileset>
-
- <!-- For Maven builds: use the compile_classpath -->
- <pathelement path="${compile_classpath}" />
- </path>
-
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
- <!-- Different location in more recent versions of Mylyn (Luna ?) -->
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
-
- <target name="build" description="Generate Eclipse help content for the Linux Tools TMF Developer Guide">
- <wikitext-to-eclipse-help markupLanguage="MediaWiki"
- validate="true"
- failonvalidationerror="true"
- overwrite="true"
- multipleOutputFiles="true"
- navigationimages="true"
- title="${ug.title}"
- formatoutput="true"
- helpPrefix="doc">
- <fileset dir="doc">
- <include name="Developer-Guide.mediawiki" />
- </fileset>
- <stylesheet url="book.css" />
- </wikitext-to-eclipse-help>
- <antcall target="test" />
- </target>
-
- <target name="test" description="Verify that all of the HTML files are well-formed XML">
- <!--
- Don't bother with DTD validation: we only care if the files are well-formed.
- We therefore provide an empty DTD
- -->
- <xmlvalidate lenient="true">
- <fileset dir="doc">
- <include name="**/*.html" />
- </fileset>
- <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
- </xmlvalidate>
- </target>
-
- <target name ="clean" description="Delete all generated files">
- <delete failonerror="false">
- <fileset dir="doc" includes="**/*.html" />
- <fileset dir="doc" includes="**/*.xml" />
- </delete>
- </target>
-
-</project>
+++ /dev/null
-*.html
-*.xml
+++ /dev/null
-
-= Introduction =
-
-The purpose of the '''Tracing Monitoring Framework (TMF)''' is to facilitate the integration of tracing and monitoring tools into Eclipse, to provide out-of-the-box generic functionalities/views and provide extension mechanisms of the base functionalities for application specific purposes.
-
-= Implementing a New Trace Type =
-
-The framework can easily be extended to support more trace types. To make a new trace type, one must define the following items:
-
-* The event type
-* The trace reader
-* The trace context
-* The trace location
-* The ''org.eclipse.linuxtools.tmf.core.tracetype'' plug-in extension point
-* (Optional) The ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point
-
-The '''event type''' must implement an ''ITmfEvent'' or extend a class that implements an ''ITmfEvent''. Typically it will extend ''TmfEvent''. The event type must contain all the data of an event. The '''trace reader''' must be of an ''ITmfTrace'' type. The ''TmfTrace'' class will supply many background operations so that the reader only needs to implement certain functions. The '''trace context''' can be seen as the internals of an iterator. It is required by the trace reader to parse events as it iterates the trace and to keep track of its rank and location. It can have a timestamp, a rank, a file position, or any other element, it should be considered to be ephemeral. The '''trace location''' is an element that is cloned often to store checkpoints, it is generally persistent. It is used to rebuild a context, therefore, it needs to contain enough information to unambiguously point to one and only one event. Finally the ''tracetype'' plug-in extension associates a given trace, non-programmatically to a trace type for use in the UI.
-
-== An Example: Nexus-lite parser ==
-
-=== Description of the file ===
-
-This is a very small subset of the nexus trace format, with some changes to make it easier to read. There is one file. This file starts with 64 Strings containing the event names, then an arbitrarily large number of events. The events are each 64 bits long. the first 32 are the timestamp in microseconds, the second 32 are split into 6 bits for the event type, and 26 for the data payload.
-
-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.
-
-<pre>
-Startup,Stop,Load,Add, ... ,reserved\n
-</pre>
-
-Then there will be the events in this format
-
-{| width= "85%"
-|style="width: 50%; background-color: #ffffcc;"|timestamp (32 bits)
-|style="width: 10%; background-color: #ffccff;"|type (6 bits)
-|style="width: 40%; background-color: #ccffcc;"|payload (26 bits)
-|-
-|style="background-color: #ffcccc;" colspan="3"|64 bits total
-|}
-
-all events will be the same size (64 bits).
-
-=== NexusLite Plug-in ===
-
-Create a '''New''', '''Project...''', '''Plug-in Project''', set the title to '''com.example.nexuslite''', click '''Next >''' then click on '''Finish'''.
-
-Now the structure for the Nexus trace Plug-in is set up.
-
-Add a dependency to TMF core and UI by opening the '''MANIFEST.MF''' in '''META-INF''', selecting the '''Dependencies''' tab and '''Add ...''' '''org.eclipse.linuxtools.tmf.core''' and '''org.eclipse.linuxtools.tmf.ui'''.
-
-[[Image:images/NTTAddDepend.png]]<br>
-[[Image:images/NTTSelectProjects.png]]<br>
-
-Now the project can access TMF classes.
-
-=== Trace Event ===
-
-The '''TmfEvent''' class will work for this example. No code required.
-
-=== Trace Reader ===
-
-The trace reader will extend a '''TmfTrace''' class.
-
-It will need to implement:
-
-* validate (is the trace format valid?)
-
-* initTrace (called as the trace is opened
-
-* seekEvent (go to a position in the trace and create a context)
-
-* getNext (implemented in the base class)
-
-* parseEvent (read the next element in the trace)
-
-For reference, there is an example implementation of the Nexus Trace file in
-org.eclipse.linuxtools.tracing.examples.core.trace.nexus.NexusTrace.java.
-
-In this example, the '''validate''' function checks first checks if the file
-exists, then makes sure that it is really a file, and not a directory. Then we
-attempt to read the file header, to make sure that it is really a Nexus Trace.
-If that check passes, we return a TmfValidationStatus with a confidence of 20.
-
-Typically, TmfValidationStatus confidences should range from 1 to 100. 1 meaning
-"there is a very small chance that this trace is of this type", and 100 meaning
-"it is this type for sure, and cannot be anything else". At run-time, the
-auto-detection will pick the the type which returned the highest confidence. So
-checks of the type "does the file exist?" should not return a too high
-confidence.
-
-Here we used a confidence of 20, to leave "room" for more specific trace types
-in the Nexus format that could be defined in TMF.
-
-The '''initTrace''' function will read the event names, and find where the data starts. After this, the number of events is known, and since each event is 8 bytes long according to the specs, the seek is then trivial.
-
-The '''seek''' here will just reset the reader to the right location.
-
-The '''parseEvent''' method needs to parse and return the current event and store the current location.
-
-The '''getNext''' method (in base class) will read the next event and update the context. It calls the '''parseEvent''' method to read the event and update the location. It does not need to be overridden and in this example it is not. The sequence of actions necessary are parse the next event from the trace, create an '''ITmfEvent''' with that data, update the current location, call '''updateAttributes''', update the context then return the event.
-
-Traces will typically implement an index, to make seeking faster. The index can
-be rebuilt every time the trace is opened. Alternatively, it can be saved to
-disk, to make future openings of the same trace quicker. To do so, the trace
-object can implement the '''ITmfPersistentlyIndexable''' interface.
-
-=== Trace Context ===
-
-The trace context will be a '''TmfContext'''
-
-=== Trace Location ===
-
-The trace location will be a long, representing the rank in the file. The '''TmfLongLocation''' will be the used, once again, no code is required.
-
-=== The ''org.eclipse.linuxtools.tmf.core.tracetype'' and ''org.eclipse.linuxtools.tmf.ui.tracetypeui'' plug-in extension point ===
-
-One should implement the ''tmf.core.tracetype'' extension in their own plug-in.
-In this example, the Nexus trace plug-in will be modified.
-
-The '''plugin.xml''' file in the ui plug-in needs to be updated if one wants users to access the given event type. It can be updated in the Eclipse plug-in editor.
-
-# In Extensions tab, add the '''org.eclipse.linuxtools.tmf.core.tracetype''' extension point.
-[[Image:images/NTTExtension.png]]<br>
-[[Image:images/NTTTraceType.png]]<br>
-[[Image:images/NTTExtensionPoint.png]]<br>
-
-# 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'''.
-
-[[Image:images/NTTAddType.png]]<br>
-
-The '''id''' is the unique identifier used to refer to the trace.
-
-The '''name''' is the field that shall be displayed when a trace type is selected.
-
-The '''trace type''' is the canonical path refering to the class of the trace.
-
-The '''event type''' is the canonical path refering to the class of the events of a given trace.
-
-The '''category''' (optional) is the container in which this trace type will be stored.
-
-# (Optional) To also add UI-specific properties to your trace type, use the '''org.eclipse.linuxtools.tmf.ui.tracetypeui''' extension. To do that,
-'''right click''' on the extension then in the context menu, go to
-'''New >''', '''type'''.
-
-The '''tracetype''' here is the '''id''' of the
-''org.eclipse.linuxtools.tmf.core.tracetype'' mentioned above.
-
-The '''icon''' is the image to associate with that trace type.
-
-In the end, the extension menu should look like this.
-
-[[Image:images/NTTPluginxmlComplete.png]]<br>
-
-== Other Considerations ==
-The ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable'' provides additional features that are active when the event class (defined in '''event type''') implements certain additional interfaces.
-
-=== Collapsing of repetitive events ===
-By implementing the interface ''org.eclipse.linuxtools.tmf.core.event.collapse.ITmfCollapsibleEvent'' the events table will allow to collapse repetitive events by selecting the menu item '''Collapse Events''' after pressing the right mouse button in the table.
-
-== Best Practices ==
-
-* Do not load the whole trace in RAM, it will limit the size of the trace that can be read.
-* Reuse as much code as possible, it makes the trace format much easier to maintain.
-* Use Eclipse's editor instead of editing the XML directly.
-* Do not forget Java supports only signed data types, there may be special care needed to handle unsigned data.
-* If the support for your trace has custom UI elements (like icons, views, etc.), split the core and UI parts in separate plugins, named identically except for a ''.core'' or ''.ui'' suffix.
-** Implement the ''tmf.core.tracetype'' extension in the core plugin, and the ''tmf.ui.tracetypeui'' extension in the UI plugin if applicable.
-
-== Download the Code ==
-
-The described example is available in the
-org.eclipse.linuxtools.tracing.examples.(tests.)trace.nexus packages with a
-trace generator and a quick test case.
-
-== Optional Trace Type Attributes ==
-
-After defining the trace type as described in the previous chapters it is possible to define optional attributes for the trace type.
-
-=== Default Editor ===
-
-The '''defaultEditor''' attribute of the '''org.eclipse.tmf.ui.tracetypeui'''
-extension point allows for configuring the editor to use for displaying the
-events. If omitted, the ''TmfEventsEditor'' is used as default.
-
-To configure an editor, first add the '''defaultEditor''' attribute to the trace
-type in the extension definition. This can be done by selecting the trace type
-in the plug-in manifest editor. Then click the right mouse button and select
-'''New -> defaultEditor''' in the context sensitive menu. Then select the newly
-added attribute. Now you can specify the editor id to use on the right side of
-the manifest editor. For example, this attribute could be used to implement an
-extension of the class ''org.eclipse.ui.part.MultiPageEditor''. The first page
-could use the ''TmfEventsEditor''' to display the events in a table as usual and
-other pages can display other aspects of the trace.
-
-=== Events Table Type ===
-
-The '''eventsTableType''' attribute of the '''org.eclipse.tmf.ui.tracetypeui'''
-extension point allows for configuring the events table class to use in the
-default events editor. If omitted, the default events table will be used.
-
-To configure a trace type specific events table, first add the
-'''eventsTableType''' attribute to the trace type in the extension definition.
-This can be done by selecting the trace type in the plug-in manifest editor.
-Then click the right mouse button and select '''New -> eventsTableType''' in the
-context sensitive menu. Then select the newly added attribute and click on
-''class'' on the right side of the manifest editor. The new class wizard will
-open. The ''superclass'' field will be already filled with the class ''org.eclipse.linuxtools.tmf.ui.viewers.events.TmfEventsTable''.
-
-By using this attribute, a table with different columns than the default columns
-can be defined. See the class org.eclipse.linuxtools.internal.lttng2.kernel.ui.viewers.events.Lttng2EventsTable
-for an example implementation.
-
-= View Tutorial =
-
-This tutorial describes how to create a simple view using the TMF framework and the SWTChart library. SWTChart is a library based on SWT that can draw several types of charts including a line chart which we will use in this tutorial. We will create a view containing a line chart that displays time stamps on the X axis and the corresponding event values on the Y axis.
-
-This tutorial will cover concepts like:
-
-* Extending TmfView
-* Signal handling (@TmfSignalHandler)
-* Data requests (TmfEventRequest)
-* SWTChart integration
-
-'''Note''': TMF 3.0.0 provides base implementations for generating SWTChart viewers and views. For more details please refer to chapter [[#TMF Built-in Views and Viewers]].
-
-=== Prerequisites ===
-
-The tutorial is based on Eclipse 4.4 (Eclipse Luna), TMF 3.0.0 and SWTChart 0.7.0. If you are using TMF from the source repository, SWTChart is already included in the target definition file (see org.eclipse.linuxtools.lttng.target). You can also install it manually by using the Orbit update site. http://download.eclipse.org/tools/orbit/downloads/
-
-=== Creating an Eclipse UI Plug-in ===
-
-To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
-[[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
-
-[[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
-
-[[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
-
-=== Creating a View ===
-
-To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
-[[Image:images/SelectManifest.png]]<br>
-
-Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf.core'' and press '''OK'''<br>
-Following the same steps, add ''org.eclipse.linuxtools.tmf.ui'' and ''org.swtchart''.<br>
-[[Image:images/AddDependencyTmfUi.png]]<br>
-
-Change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the view extension ''org.eclipse.ui.views'' and press '''Finish'''.<br>
-[[Image:images/AddViewExtension1.png]]<br>
-
-To create a view, click the right mouse button. Then select '''New -> view'''<br>
-[[Image:images/AddViewExtension2.png]]<br>
-
-A new view entry has been created. Fill in the fields ''id'' 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>
-[[Image:images/FillSampleViewExtension.png]]<br>
-
-This will generate an empty class. Once the quick fixes are applied, the following code is obtained:
-
-<pre>
-package org.eclipse.linuxtools.tmf.sample.ui;
-
-import org.eclipse.swt.widgets.Composite;
-import org.eclipse.ui.part.ViewPart;
-
-public class SampleView extends TmfView {
-
- public SampleView(String viewName) {
- super(viewName);
- // TODO Auto-generated constructor stub
- }
-
- @Override
- public void createPartControl(Composite parent) {
- // TODO Auto-generated method stub
-
- }
-
- @Override
- public void setFocus() {
- // TODO Auto-generated method stub
-
- }
-
-}
-</pre>
-
-This creates an empty view, however the basic structure is now is place.
-
-=== Implementing a view ===
-
-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.
-
-==== Adding an Empty Chart ====
-
-First, we can add an empty chart to the view and initialize some of its components.
-
-<pre>
- private static final String SERIES_NAME = "Series";
- private static final String Y_AXIS_TITLE = "Signal";
- private static final String X_AXIS_TITLE = "Time";
- private static final String FIELD = "value"; // The name of the field that we want to display on the Y axis
- private static final String VIEW_ID = "org.eclipse.linuxtools.tmf.sample.ui.view";
- private Chart chart;
- private ITmfTrace currentTrace;
-
- public SampleView() {
- super(VIEW_ID);
- }
-
- @Override
- public void createPartControl(Composite parent) {
- chart = new Chart(parent, SWT.BORDER);
- chart.getTitle().setVisible(false);
- chart.getAxisSet().getXAxis(0).getTitle().setText(X_AXIS_TITLE);
- chart.getAxisSet().getYAxis(0).getTitle().setText(Y_AXIS_TITLE);
- chart.getSeriesSet().createSeries(SeriesType.LINE, SERIES_NAME);
- chart.getLegend().setVisible(false);
- }
-
- @Override
- public void setFocus() {
- chart.setFocus();
- }
-</pre>
-
-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>
-[[Image:images/RunEclipseApplication.png]]<br>
-
-A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample View'''.<br>
-[[Image:images/ShowViewOther.png]]<br>
-
-You should now see a view containing an empty chart<br>
-[[Image:images/EmptySampleView.png]]<br>
-
-==== Signal Handling ====
-
-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.
-
-<pre>
- @TmfSignalHandler
- public void traceSelected(final TmfTraceSelectedSignal signal) {
-
- }
-</pre>
-
-==== Requesting Data ====
-
-Then we need to actually gather data from the trace. This is done asynchronously using a ''TmfEventRequest''
-
-<pre>
- @TmfSignalHandler
- public void traceSelected(final TmfTraceSelectedSignal signal) {
- // Don't populate the view again if we're already showing this trace
- if (currentTrace == signal.getTrace()) {
- return;
- }
- currentTrace = signal.getTrace();
-
- // Create the request to get data from the trace
-
- TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
- TmfTimeRange.ETERNITY, 0, ITmfEventRequest.ALL_DATA,
- ITmfEventRequest.ExecutionType.BACKGROUND) {
-
- @Override
- public void handleData(ITmfEvent data) {
- // Called for each event
- super.handleData(data);
- }
-
- @Override
- public void handleSuccess() {
- // Request successful, not more data available
- super.handleSuccess();
- }
-
- @Override
- public void handleFailure() {
- // Request failed, not more data available
- super.handleFailure();
- }
- };
- ITmfTrace trace = signal.getTrace();
- trace.sendRequest(req);
- }
-</pre>
-
-==== Transferring Data to the Chart ====
-
-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.
-
-<pre>
- TmfEventRequest req = new TmfEventRequest(TmfEvent.class,
- TmfTimeRange.ETERNITY, 0, ITmfEventRequest.ALL_DATA,
- ITmfEventRequest.ExecutionType.BACKGROUND) {
-
- ArrayList<Double> xValues = new ArrayList<Double>();
- ArrayList<Double> yValues = new ArrayList<Double>();
-
- @Override
- public void handleData(ITmfEvent data) {
- // Called for each event
- super.handleData(data);
- ITmfEventField field = data.getContent().getField(FIELD);
- if (field != null) {
- yValues.add((Double) field.getValue());
- xValues.add((double) data.getTimestamp().getValue());
- }
- }
-
- @Override
- public void handleSuccess() {
- // Request successful, not more data available
- super.handleSuccess();
-
- final double x[] = toArray(xValues);
- final double y[] = toArray(yValues);
-
- // This part needs to run on the UI thread since it updates the chart SWT control
- Display.getDefault().asyncExec(new Runnable() {
-
- @Override
- public void run() {
- chart.getSeriesSet().getSeries()[0].setXSeries(x);
- chart.getSeriesSet().getSeries()[0].setYSeries(y);
-
- chart.redraw();
- }
-
- });
- }
-
- /**
- * Convert List<Double> to double[]
- */
- private double[] toArray(List<Double> list) {
- double[] d = new double[list.size()];
- for (int i = 0; i < list.size(); ++i) {
- d[i] = list.get(i);
- }
-
- return d;
- }
- };
-</pre>
-
-==== Adjusting the Range ====
-
-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.
-
-<pre>
-
- ArrayList<Double> xValues = new ArrayList<Double>();
- ArrayList<Double> yValues = new ArrayList<Double>();
- private double maxY = -Double.MAX_VALUE;
- private double minY = Double.MAX_VALUE;
- private double maxX = -Double.MAX_VALUE;
- private double minX = Double.MAX_VALUE;
-
- @Override
- public void handleData(ITmfEvent data) {
- super.handleData(data);
- ITmfEventField field = data.getContent().getField(FIELD);
- if (field != null) {
- Double yValue = (Double) field.getValue();
- minY = Math.min(minY, yValue);
- maxY = Math.max(maxY, yValue);
- yValues.add(yValue);
-
- double xValue = (double) data.getTimestamp().getValue();
- xValues.add(xValue);
- minX = Math.min(minX, xValue);
- maxX = Math.max(maxX, xValue);
- }
- }
-
- @Override
- public void handleSuccess() {
- super.handleSuccess();
- final double x[] = toArray(xValues);
- final double y[] = toArray(yValues);
-
- // This part needs to run on the UI thread since it updates the chart SWT control
- Display.getDefault().asyncExec(new Runnable() {
-
- @Override
- public void run() {
- chart.getSeriesSet().getSeries()[0].setXSeries(x);
- chart.getSeriesSet().getSeries()[0].setYSeries(y);
-
- // Set the new range
- if (!xValues.isEmpty() && !yValues.isEmpty()) {
- chart.getAxisSet().getXAxis(0).setRange(new Range(0, x[x.length - 1]));
- chart.getAxisSet().getYAxis(0).setRange(new Range(minY, maxY));
- } else {
- chart.getAxisSet().getXAxis(0).setRange(new Range(0, 1));
- chart.getAxisSet().getYAxis(0).setRange(new Range(0, 1));
- }
- chart.getAxisSet().adjustRange();
-
- chart.redraw();
- }
- });
- }
-</pre>
-
-==== Formatting the Time Stamps ====
-
-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.
-
-<pre>
- @Override
- public void createPartControl(Composite parent) {
- ...
-
- chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
- }
-
- public class TmfChartTimeStampFormat extends SimpleDateFormat {
- private static final long serialVersionUID = 1L;
- @Override
- public StringBuffer format(Date date, StringBuffer toAppendTo, FieldPosition fieldPosition) {
- long time = date.getTime();
- toAppendTo.append(TmfTimestampFormat.getDefaulTimeFormat().format(time));
- return toAppendTo;
- }
- }
-
- @TmfSignalHandler
- public void timestampFormatUpdated(TmfTimestampFormatUpdateSignal signal) {
- // Called when the time stamp preference is changed
- chart.getAxisSet().getXAxis(0).getTick().setFormat(new TmfChartTimeStampFormat());
- chart.redraw();
- }
-</pre>
-
-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.
-
-<pre>
- @Override
- public void createPartControl(Composite parent) {
- ...
-
- ITmfTrace trace = getActiveTrace();
- if (trace != null) {
- traceSelected(new TmfTraceSelectedSignal(this, trace));
- }
- }
-</pre>
-
-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>
-
-[[Image:images/SampleView.png]]<br>
-
-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.
-
-== TMF Built-in Views and Viewers ==
-
-TMF provides base implementations for several types of views and viewers for generating custom X-Y-Charts, Time Graphs, or Trees. They are well integrated with various TMF features such as reading traces and time synchronization with other views. They also handle mouse events for navigating the trace and view, zooming or presenting detailed information at mouse position. The code can be found in the TMF UI plug-in ''org.eclipse.linuxtools.tmf.ui''. See below for a list of relevant java packages:
-
-* Generic
-** ''org.eclipse.linuxtools.tmf.ui.views'': Common TMF view base classes
-* X-Y-Chart
-** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts'': Common base classes for X-Y-Chart viewers based on SWTChart
-** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.barcharts'': Base classes for bar charts
-** ''org.eclipse.linuxtools.tmf.ui.viewers.xycharts.linecharts'': Base classes for line charts
-* Time Graph View
-** ''org.eclipse.linuxtools.tmf.ui.widgets.timegraph'': Base classes for time graphs e.g. Gantt-charts
-* Tree Viewer
-** ''org.eclipse.linuxtools.tmf.ui.viewers.tree'': Base classes for TMF specific tree viewers
-
-Several features in TMF and the Eclipse LTTng integration are using this framework and can be used as example for further developments:
-* X-Y- Chart
-** ''org.eclipse.linuxtools.internal.lttng2.ust.ui.views.memusage.MemUsageView.java''
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageView.java''
-** ''org.eclipse.linuxtools.tracing.examples.ui.views.histogram.NewHistogramView.java''
-* Time Graph View
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.controlflow.ControlFlowView.java''
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.resources.ResourcesView.java''
-* Tree Viewer
-** ''org.eclipse.linuxtools.tmf.ui.views.statesystem.TmfStateSystemExplorer.java''
-** ''org.eclipse.linuxtools.internal.lttng2.kernel.ui.views.cpuusage.CpuUsageComposite.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.
-
-The TMF Signal Manager handles registration of components and the broadcasting of signals to their intended receivers.
-
-Components can register as VIP receivers which will ensure they will receive the signal before non-VIP receivers.
-
-== Sending Signals ==
-
-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.
-
-<pre>
-TmfExampleSignal signal = new TmfExampleSignal(this, ...);
-TmfSignalManager.dispatchSignal(signal);
-</pre>
-
-If the sender is an instance of the class TmfComponent, the broadcast method can be used:
-
-<pre>
-TmfExampleSignal signal = new TmfExampleSignal(this, ...);
-broadcast(signal);
-</pre>
-
-== Receiving Signals ==
-
-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.
-
-<pre>
-TmfSignalManager.register(this);
-TmfSignalManager.registerVIP(this);
-</pre>
-
-If the receiver is an instance of the class TmfComponent, it is automatically registered as a normal receiver in the constructor.
-
-When the receiver is destroyed or disposed, it should deregister itself from the signal manager.
-
-<pre>
-TmfSignalManager.deregister(this);
-</pre>
-
-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.
-
-<pre>
-@TmfSignalHandler
-public void example(TmfExampleSignal signal) {
- ...
-}
-</pre>
-
-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.
-
-== Signal Throttling ==
-
-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.
-
-The signal throttler must first be initialized:
-
-<pre>
-final int delay = 100; // in ms
-TmfSignalThrottler throttler = new TmfSignalThrottler(this, delay);
-</pre>
-
-Then the sending of signals should be queued through the throttler:
-
-<pre>
-TmfExampleSignal signal = new TmfExampleSignal(this, ...);
-throttler.queue(signal);
-</pre>
-
-When the throttler is no longer needed, it should be disposed:
-
-<pre>
-throttler.dispose();
-</pre>
-
-== Signal Reference ==
-
-The following is a list of built-in signals defined in the framework.
-
-=== TmfStartSynchSignal ===
-
-''Purpose''
-
-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.
-
-''Senders''
-
-Sent by TmfSignalManager before dispatching a signal to all receivers.
-
-''Receivers''
-
-Received by TmfDataProvider.
-
-=== TmfEndSynchSignal ===
-
-''Purpose''
-
-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.
-
-''Senders''
-
-Sent by TmfSignalManager after dispatching a signal to all receivers.
-
-''Receivers''
-
-Received by TmfDataProvider.
-
-=== TmfTraceOpenedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a trace has been opened in an editor.
-
-''Senders''
-
-Sent by a TmfEventsEditor instance when it is created.
-
-''Receivers''
-
-Received by TmfTrace, TmfExperiment, TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
-
-=== TmfTraceSelectedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a trace has become the currently selected trace.
-
-''Senders''
-
-Sent by a TmfEventsEditor instance when it receives focus. Components can send this signal to make a trace editor be brought to front.
-
-''Receivers''
-
-Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
-
-=== TmfTraceClosedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a trace editor has been closed.
-
-''Senders''
-
-Sent by a TmfEventsEditor instance when it is disposed.
-
-''Receivers''
-
-Received by TmfTraceManager and every view that shows trace data. Components that show trace data should handle this signal.
-
-=== TmfTraceRangeUpdatedSignal ===
-
-''Purpose''
-
-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.
-
-''Senders''
-
-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.
-
-''Receivers''
-
-Received by TmfTrace, TmfExperiment and components that process trace events. Components that need to process trace events should handle this signal.
-
-=== TmfTraceUpdatedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that new events have been indexed for a trace.
-
-''Senders''
-
-Sent by TmfCheckpointIndexer when new events have been indexed and the number of events has changed.
-
-''Receivers''
-
-Received by components that need to be notified of a new trace event count.
-
-=== TmfTimeSynchSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a new time or time range has been
-selected. It contains a begin and end time. If a single time is selected then
-the begin and end time are the same.
-
-''Senders''
-
-Sent by any component that allows the user to select a time or time range.
-
-''Receivers''
-
-Received by any component that needs to be notified of the currently selected time or time range.
-
-=== TmfRangeSynchSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a new time range window has been set.
-
-''Senders''
-
-Sent by any component that allows the user to set a time range window.
-
-''Receivers''
-
-Received by any component that needs to be notified of the current visible time range window.
-
-=== TmfEventFilterAppliedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a filter has been applied to a trace.
-
-''Senders''
-
-Sent by TmfEventsTable when a filter is applied.
-
-''Receivers''
-
-Received by any component that shows trace data and needs to be notified of applied filters.
-
-=== TmfEventSearchAppliedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that a search has been applied to a trace.
-
-''Senders''
-
-Sent by TmfEventsTable when a search is applied.
-
-''Receivers''
-
-Received by any component that shows trace data and needs to be notified of applied searches.
-
-=== TmfTimestampFormatUpdateSignal ===
-
-''Purpose''
-
-This signal is used to indicate that the timestamp format preference has been updated.
-
-''Senders''
-
-Sent by TmfTimestampFormat when the default timestamp format preference is changed.
-
-''Receivers''
-
-Received by any component that needs to refresh its display for the new timestamp format.
-
-=== TmfStatsUpdatedSignal ===
-
-''Purpose''
-
-This signal is used to indicate that the statistics data model has been updated.
-
-''Senders''
-
-Sent by statistic providers when new statistics data has been processed.
-
-''Receivers''
-
-Received by statistics viewers and any component that needs to be notified of a statistics update.
-
-=== TmfPacketStreamSelected ===
-
-''Purpose''
-
-This signal is used to indicate that the user has selected a packet stream to analyze.
-
-''Senders''
-
-Sent by the Stream List View when the user selects a new packet stream.
-
-''Receivers''
-
-Received by views that analyze packet streams.
-
-== Debugging ==
-
-TMF has built-in Eclipse tracing support for the debugging of signal interaction between components. To enable it, open the '''Run/Debug Configuration...''' dialog, select a configuration, click the '''Tracing''' tab, select the plug-in '''org.eclipse.linuxtools.tmf.core''', and check the '''signal''' item.
-
-All signals sent and received will be logged to the file TmfTrace.log located in the Eclipse home directory.
-
-= Generic State System =
-
-== Introduction ==
-
-The Generic State System is a utility available in TMF to track different states
-over the duration of a trace. It works by first sending some or all events of
-the trace into a state provider, which defines the state changes for a given
-trace type. Once built, views and analysis modules can then query the resulting
-database of states (called "state history") to get information.
-
-For example, let's suppose we have the following sequence of events in a kernel
-trace:
-
- 10 s, sys_open, fd = 5, file = /home/user/myfile
- ...
- 15 s, sys_read, fd = 5, size=32
- ...
- 20 s, sys_close, fd = 5
-
-Now let's say we want to implement an analysis module which will track the
-amount of bytes read and written to each file. Here, of course the sys_read is
-interesting. However, by just looking at that event, we have no information on
-which file is being read, only its fd (5) is known. To get the match
-fd5 = /home/user/myfile, we have to go back to the sys_open event which happens
-5 seconds earlier.
-
-But since we don't know exactly where this sys_open event is, we will have to go
-back to the very start of the trace, and look through events one by one! This is
-obviously not efficient, and will not scale well if we want to analyze many
-similar patterns, or for very large traces.
-
-A solution in this case would be to use the state system to keep track of the
-amount of bytes read/written to every *filename* (instead of every file
-descriptor, like we get from the events). Then the module could ask the state
-system "what is the amount of bytes read for file "/home/user/myfile" at time
-16 s", and it would return the answer "32" (assuming there is no other read
-than the one shown).
-
-== High-level components ==
-
-The State System infrastructure is composed of 3 parts:
-* The state provider
-* The central state system
-* The storage backend
-
-The state provider is the customizable part. This is where the mapping from
-trace events to state changes is done. This is what you want to implement for
-your specific trace type and analysis type. It's represented by the
-ITmfStateProvider interface (with a threaded implementation in
-AbstractTmfStateProvider, which you can extend).
-
-The core of the state system is exposed through the ITmfStateSystem and
-ITmfStateSystemBuilder interfaces. The former allows only read-only access and
-is typically used for views doing queries. The latter also allows writing to the
-state history, and is typically used by the state provider.
-
-Finally, each state system has its own separate backend. This determines how the
-intervals, or the "state history", are saved (in RAM, on disk, etc.) You can
-select the type of backend at construction time in the TmfStateSystemFactory.
-
-== Definitions ==
-
-Before we dig into how to use the state system, we should go over some useful
-definitions:
-
-=== Attribute ===
-
-An attribute is the smallest element of the model that can be in any particular
-state. When we refer to the "full state", in fact it means we are interested in
-the state of every single attribute of the model.
-
-=== Attribute Tree ===
-
-Attributes in the model can be placed in a tree-like structure, a bit like files
-and directories in a file system. However, note that an attribute can always
-have both a value and sub-attributes, so they are like files and directories at
-the same time. We are then able to refer to every single attribute with its
-path in the tree.
-
-For example, in the attribute tree for LTTng kernel traces, we use the following
-attributes, among others:
-
-<pre>
-|- Processes
-| |- 1000
-| | |- PPID
-| | |- Exec_name
-| |- 1001
-| | |- PPID
-| | |- Exec_name
-| ...
-|- CPUs
- |- 0
- | |- Status
- | |- Current_pid
- ...
-</pre>
-
-In this model, the attribute "Processes/1000/PPID" refers to the PPID of process
-with PID 1000. The attribute "CPUs/0/Status" represents the status (running,
-idle, etc.) of CPU 0. "Processes/1000/PPID" and "Processes/1001/PPID" are two
-different attribute, even though their base name is the same: the whole path is
-the unique identifier.
-
-The value of each attribute can change over the duration of the trace,
-independently of the other ones, and independently of its position in the tree.
-
-The tree-like organization is optional, all attributes could be at the same
-level. But it's possible to put them in a tree, and it helps make things
-clearer.
-
-=== Quark ===
-
-In addition to a given path, each attribute also has a unique integer
-identifier, called the "quark". To continue with the file system analogy, this
-is like the inode number. When a new attribute is created, a new unique quark
-will be assigned automatically. They are assigned incrementally, so they will
-normally be equal to their order of creation, starting at 0.
-
-Methods are offered to get the quark of an attribute from its path. The API
-methods for inserting state changes and doing queries normally use quarks
-instead of paths. This is to encourage users to cache the quarks and re-use
-them, which avoids re-walking the attribute tree over and over, which avoids
-unneeded hashing of strings.
-
-=== State value ===
-
-The path and quark of an attribute will remain constant for the whole duration
-of the trace. However, the value carried by the attribute will change. The value
-of a specific attribute at a specific time is called the state value.
-
-In the TMF implementation, state values can be integers, longs, doubles, or strings.
-There is also a "null value" type, which is used to indicate that no particular
-value is active for this attribute at this time, but without resorting to a
-'null' reference.
-
-Any other type of value could be used, as long as the backend knows how to store
-it.
-
-Note that the TMF implementation also forces every attribute to always carry the
-same type of state value. This is to make it simpler for views, so they can
-expect that an attribute will always use a given type, without having to check
-every single time. Null values are an exception, they are always allowed for all
-attributes, since they can safely be "unboxed" into all types.
-
-=== State change ===
-
-A state change is the element that is inserted in the state system. It consists
-of:
-* a timestamp (the time at which the state change occurs)
-* an attribute (the attribute whose value will change)
-* a state value (the new value that the attribute will carry)
-
-It's not an object per se in the TMF implementation (it's represented by a
-function call in the state provider). Typically, the state provider will insert
-zero, one or more state changes for every trace event, depending on its event
-type, payload, etc.
-
-Note, we use "timestamp" here, but it's in fact a generic term that could be
-referred to as "index". For example, if a given trace type has no notion of
-timestamp, the event rank could be used.
-
-In the TMF implementation, the timestamp is a long (64-bit integer).
-
-=== State interval ===
-
-State changes are inserted into the state system, but state intervals are the
-objects that come out on the other side. Those are stocked in the storage
-backend. A state interval represents a "state" of an attribute we want to track.
-When doing queries on the state system, intervals are what is returned. The
-components of a state interval are:
-* Start time
-* End time
-* State value
-* Quark
-
-The start and end times represent the time range of the state. The state value
-is the same as the state value in the state change that started this interval.
-The interval also keeps a reference to its quark, although you normally know
-your quark in advance when you do queries.
-
-=== State history ===
-
-The state history is the name of the container for all the intervals created by
-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.
-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.
-
-=== Construction phase ===
-
-Before we can query a state system, we need to build the state history first. To
-do so, trace events are sent one-by-one through the state provider, which in
-turn sends state changes to the central component, which then creates intervals
-and stores them in the backend. This is called the construction phase.
-
-Note that the state system needs to receive its events into chronological order.
-This phase will end once the end of the trace is reached.
-
-Also note that it is possible to query the state system while it is being build.
-Any timestamp between the start of the trace and the current end time of the
-state system (available with ITmfStateSystem#getCurrentEndTime()) is a valid
-timestamp that can be queried.
-
-=== Queries ===
-
-As mentioned previously, when doing queries on the state system, the returned
-objects will be state intervals. In most cases it's the state *value* we are
-interested in, but since the backend has to instantiate the interval object
-anyway, there is no additional cost to return the interval instead. This way we
-also get the start and end times of the state "for free".
-
-There are two types of queries that can be done on the state system:
-
-==== Full queries ====
-
-A full query means that we want to retrieve the whole state of the model for one
-given timestamp. As we remember, this means "the state of every single attribute
-in the model". As parameter we only need to pass the timestamp (see the API
-methods below). The return value will be an array of intervals, where the offset
-in the array represents the quark of each attribute.
-
-==== Single queries ====
-
-In other cases, we might only be interested in the state of one particular
-attribute at one given timestamp. For these cases it's better to use a
-single query. For a single query. we need to pass both a timestamp and a
-quark in parameter. The return value will be a single interval, representing
-the state that this particular attribute was at that time.
-
-Single queries are typically faster than full queries (but once again, this
-depends on the backend that is used), but not by much. Even if you only want the
-state of say 10 attributes out of 200, it could be faster to use a full query
-and only read the ones you need. Single queries should be used for cases where
-you only want one attribute per timestamp (for example, if you follow the state
-of the same attribute over a time range).
-
-
-== Relevant interfaces/classes ==
-
-This section will describe the public interface and classes that can be used if
-you want to use the state system.
-
-=== Main classes in org.eclipse.linuxtools.tmf.core.statesystem ===
-
-==== ITmfStateProvider / AbstractTmfStateProvider ====
-
-ITmfStateProvider is the interface you have to implement to define your state
-provider. This is where most of the work has to be done to use a state system
-for a custom trace type or analysis type.
-
-For first-time users, it's recommended to extend AbstractTmfStateProvider
-instead. This class takes care of all the initialization mumbo-jumbo, and also
-runs the event handler in a separate thread. You will only need to implement
-eventHandle, which is the call-back that will be called for every event in the
-trace.
-
-For an example, you can look at StatsStateProvider in the TMF tree, or at the
-small example below.
-
-==== TmfStateSystemFactory ====
-
-Once you have defined your state provider, you need to tell your trace type to
-build a state system with this provider during its initialization. This consists
-of overriding TmfTrace#buildStateSystems() and in there of calling the method in
-TmfStateSystemFactory that corresponds to the storage backend you want to use
-(see the section [[#Comparison of state system backends]]).
-
-You will have to pass in parameter the state provider you want to use, which you
-should have defined already. Each backend can also ask for more configuration
-information.
-
-You must then call registerStateSystem(id, statesystem) to make your state
-system visible to the trace objects and the views. The ID can be any string of
-your choosing. To access this particular state system, the views or modules will
-need to use this ID.
-
-Also, don't forget to call super.buildStateSystems() in your implementation,
-unless you know for sure you want to skip the state providers built by the
-super-classes.
-
-You can look at how LttngKernelTrace does it for an example. It could also be
-possible to build a state system only under certain conditions (like only if the
-trace contains certain event types).
-
-
-==== ITmfStateSystem ====
-
-ITmfStateSystem is the main interface through which views or analysis modules
-will access the state system. It offers a read-only view of the state system,
-which means that no states can be inserted, and no attributes can be created.
-Calling TmfTrace#getStateSystems().get(id) will return you a ITmfStateSystem
-view of the requested state system. The main methods of interest are:
-
-===== getQuarkAbsolute()/getQuarkRelative() =====
-
-Those are the basic quark-getting methods. The goal of the state system is to
-return the state values of given attributes at given timestamps. As we've seen
-earlier, attributes can be described with a file-system-like path. The goal of
-these methods is to convert from the path representation of the attribute to its
-quark.
-
-Since quarks are created on-the-fly, there is no guarantee that the same
-attributes will have the same quark for two traces of the same type. The views
-should always query their quarks when dealing with a new trace or a new state
-provider. Beyond that however, quarks should be cached and reused as much as
-possible, to avoid potentially costly string re-hashing.
-
-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.
-
-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
-the origin quark, followed by a String varagrs which represent the relative path
-to the final attribute.
-
-These two methods will throw an AttributeNotFoundException if trying to access
-an attribute that does not exist in the model.
-
-These methods also imply that the view has the knowledge of how the attribute
-tree is organized. This should be a reasonable hypothesis, since the same
-analysis plugin will normally ship both the state provider and the view, and
-they will have been written by the same person. In other cases, it's possible to
-use getSubAttributes() to explore the organization of the attribute tree first.
-
-===== waitUntilBuilt() =====
-
-This is a simple method used to block the caller until the construction phase of
-this state system is done. If the view prefers to wait until all information is
-available before starting to do queries (to get all known attributes right away,
-for example), this is the guy to call.
-
-===== queryFullState() =====
-
-This is the method to do full queries. As mentioned earlier, you only need to
-pass a target timestamp in parameter. It will return a List of state intervals,
-in which the offset corresponds to the attribute quark. This will represent the
-complete state of the model at the requested time.
-
-===== querySingleState() =====
-
-The method to do single queries. You pass in parameter both a timestamp and an
-attribute quark. This will return the single state matching this
-timestamp/attribute pair.
-
-Other methods are available, you are encouraged to read their Javadoc and see if
-they can be potentially useful.
-
-==== ITmfStateSystemBuilder ====
-
-ITmfStateSystemBuilder is the read-write interface to the state system. It
-extends ITmfStateSystem itself, so all its methods are available. It then adds
-methods that can be used to write to the state system, either by creating new
-attributes of inserting state changes.
-
-It is normally reserved for the state provider and should not be visible to
-external components. However it will be available in AbstractTmfStateProvider,
-in the field 'ss'. That way you can call ss.modifyAttribute() etc. in your state
-provider to write to the state.
-
-The main methods of interest are:
-
-===== getQuark*AndAdd() =====
-
-getQuarkAbsoluteAndAdd() and getQuarkRelativeAndAdd() work exactly like their
-non-AndAdd counterparts in ITmfStateSystem. The difference is that the -AndAdd
-versions will not throw any exception: if the requested attribute path does not
-exist in the system, it will be created, and its newly-assigned quark will be
-returned.
-
-When in a state provider, the -AndAdd version should normally be used (unless
-you know for sure the attribute already exist and don't want to create it
-otherwise). This means that there is no need to define the whole attribute tree
-in advance, the attributes will be created on-demand.
-
-===== modifyAttribute() =====
-
-This is the main state-change-insertion method. As was explained before, a state
-change is defined by a timestamp, an attribute and a state value. Those three
-elements need to be passed to modifyAttribute as parameters.
-
-Other state change insertion methods are available (increment-, push-, pop- and
-removeAttribute()), but those are simply convenience wrappers around
-modifyAttribute(). Check their Javadoc for more information.
-
-===== closeHistory() =====
-
-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.
-
-If you use the AbstractTmfStateProvider, it will call closeHistory()
-automatically when it reaches the end of the trace.
-
-=== Other relevant interfaces ===
-
-==== o.e.l.tmf.core.statevalue.ITmfStateValue ====
-
-This is the interface used to represent state values. Those are used when
-inserting state changes in the provider, and is also part of the state intervals
-obtained when doing queries.
-
-The abstract TmfStateValue class contains the factory methods to create new
-state values of either int, long, double or string types. To retrieve the real
-object inside the state value, one can use the .unbox* methods.
-
-Note: Do not instantiate null values manually, use TmfStateValue.nullValue()
-
-==== o.e.l.tmf.core.interval.ITmfStateInterval ====
-
-This is the interface to represent the state intervals, which are stored in the
-state history backend, and are returned when doing state system queries. A very
-simple implementation is available in TmfStateInterval. Its methods should be
-self-descriptive.
-
-=== Exceptions ===
-
-The following exceptions, found in o.e.l.tmf.core.exceptions, are related to
-state system activities.
-
-==== AttributeNotFoundException ====
-
-This is thrown by getQuarkRelative() and getQuarkAbsolute() (but not byt the
--AndAdd versions!) when passing an attribute path that is not present in the
-state system. This is to ensure that no new attribute is created when using
-these versions of the methods.
-
-Views can expect some attributes to be present, but they should handle these
-exceptions for when the attributes end up not being in the state system (perhaps
-this particular trace didn't have a certain type of events, etc.)
-
-==== StateValueTypeException ====
-
-This exception will be thrown when trying to unbox a state value into a type
-different than its own. You should always check with ITmfStateValue#getType()
-beforehand if you are not sure about the type of a given state value.
-
-==== TimeRangeException ====
-
-This exception is thrown when trying to do a query on the state system for a
-timestamp that is outside of its range. To be safe, you should check with
-ITmfStateSystem#getStartTime() and #getCurrentEndTime() for the current valid
-range of the state system. This is especially important when doing queries on
-a state system that is currently being built.
-
-==== StateSystemDisposedException ====
-
-This exception is thrown when trying to access a state system that has been
-disposed, with its dispose() method. This can potentially happen at shutdown,
-since Eclipse is not always consistent with the order in which the components
-are closed.
-
-
-== Comparison of state system backends ==
-
-As we have seen in section [[#High-level components]], the state system needs
-a storage backend to save the intervals. Different implementations are
-available when building your state system from TmfStateSystemFactory.
-
-Do not confuse full/single queries with full/partial history! All backend types
-should be able to handle any type of queries defined in the ITmfStateSystem API,
-unless noted otherwise.
-
-=== Full history ===
-
-Available with TmfStateSystemFactory#newFullHistory(). The full history uses a
-History Tree data structure, which is an optimized structure store state
-intervals on disk. Once built, it can respond to queries in a ''log(n)'' manner.
-
-You need to specify a file at creation time, which will be the container for
-the history tree. Once it's completely built, it will remain on disk (until you
-delete the trace from the project). This way it can be reused from one session
-to another, which makes subsequent loading time much faster.
-
-This the backend used by the LTTng kernel plugin. It offers good scalability and
-performance, even at extreme sizes (it's been tested with traces of sizes up to
-500 GB). Its main downside is the amount of disk space required: since every
-single interval is written to disk, the size of the history file can quite
-easily reach and even surpass the size of the trace itself.
-
-=== Null history ===
-
-Available with TmfStateSystemFactory#newNullHistory(). As its name implies the
-null history is in fact an absence of state history. All its query methods will
-return null (see the Javadoc in NullBackend).
-
-Obviously, no file is required, and almost no memory space is used.
-
-It's meant to be used in cases where you are not interested in past states, but
-only in the "ongoing" one. It can also be useful for debugging and benchmarking.
-
-=== In-memory history ===
-
-Available with TmfStateSystemFactory#newInMemHistory(). This is a simple wrapper
-using a TreeSet to store all state intervals in memory. The implementation at
-the moment is quite simple, it will perform a binary search on entries when
-doing queries to find the ones that match.
-
-The advantage of this method is that it's very quick to build and query, since
-all the information resides in memory. However, you are limited to 2^31 entries
-(roughly 2 billions), and depending on your state provider and trace type, that
-can happen really fast!
-
-There are no safeguards, so if you bust the limit you will end up with
-ArrayOutOfBoundsException's everywhere. If your trace or state history can be
-arbitrarily big, it's probably safer to use a Full History instead.
-
-=== Partial history ===
-
-Available with TmfStateSystemFactory#newPartialHistory(). The partial history is
-a more advanced form of the full history. Instead of writing all state intervals
-to disk like with the full history, we only write a small fraction of them, and
-go back to read the trace to recreate the states in-between.
-
-It has a big advantage over a full history in terms of disk space usage. It's
-very possible to reduce the history tree file size by a factor of 1000, while
-keeping query times within a factor of two. Its main downside comes from the
-fact that you cannot do efficient single queries with it (they are implemented
-by doing full queries underneath).
-
-This makes it a poor choice for views like the Control Flow view, where you do
-a lot of range queries and single queries. However, it is a perfect fit for
-cases like statistics, where you usually do full queries already, and you store
-lots of small states which are very easy to "compress".
-
-However, it can't really be used until bug 409630 is fixed.
-
-== State System Operations ==
-
-TmfStateSystemOperations is a static class that implements additional
-statistical operations that can be performed on attributes of the state system.
-
-These operations require that the attribute be one of the numerical values
-(int, long or double).
-
-The speed of these operations can be greatly improved for large data sets if
-the attribute was inserted in the state system as a mipmap attribute. Refer to
-the [[#Mipmap feature | Mipmap feature]] section.
-
-===== queryRangeMax() =====
-
-This method returns the maximum numerical value of an attribute in the
-specified time range. The attribute must be of type int, long or double.
-Null values are ignored. The returned value will be of the same state value
-type as the base attribute, or a null value if there is no state interval
-stored in the given time range.
-
-===== queryRangeMin() =====
-
-This method returns the minimum numerical value of an attribute in the
-specified time range. The attribute must be of type int, long or double.
-Null values are ignored. The returned value will be of the same state value
-type as the base attribute, or a null value if there is no state interval
-stored in the given time range.
-
-===== queryRangeAverage() =====
-
-This method returns the average numerical value of an attribute in the
-specified time range. The attribute must be of type int, long or double.
-Each state interval value is weighted according to time. Null values are
-counted as zero. The returned value will be a double primitive, which will
-be zero if there is no state interval stored in the given time range.
-
-== Code example ==
-
-Here is a small example of code that will use the state system. For this
-example, let's assume we want to track the state of all the CPUs in a LTTng
-kernel trace. To do so, we will watch for the "sched_switch" event in the state
-provider, and will update an attribute indicating if the associated CPU should
-be set to "running" or "idle".
-
-We will use an attribute tree that looks like this:
-<pre>
-CPUs
- |--0
- | |--Status
- |
- |--1
- | |--Status
- |
- | 2
- | |--Status
-...
-</pre>
-
-The second-level attributes will be named from the information available in the
-trace events. Only the "Status" attributes will carry a state value (this means
-we could have just used "1", "2", "3",... directly, but we'll do it in a tree
-for the example's sake).
-
-Also, we will use integer state values to represent "running" or "idle", instead
-of saving the strings that would get repeated every time. This will help in
-reducing the size of the history file.
-
-First we will define a state provider in MyStateProvider. Then, assuming we
-have already implemented a custom trace type extending CtfTmfTrace, we will add
-a section to it to make it build a state system using the provider we defined
-earlier. Finally, we will show some example code that can query the state
-system, which would normally go in a view or analysis module.
-
-=== State Provider ===
-
-<pre>
-import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfEvent;
-import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
-import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
-import org.eclipse.linuxtools.tmf.core.exceptions.StateValueTypeException;
-import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
-import org.eclipse.linuxtools.tmf.core.statesystem.AbstractTmfStateProvider;
-import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
-import org.eclipse.linuxtools.tmf.core.statevalue.TmfStateValue;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
-
-/**
- * Example state system provider.
- *
- * @author Alexandre Montplaisir
- */
-public class MyStateProvider extends AbstractTmfStateProvider {
-
- /** State value representing the idle state */
- public static ITmfStateValue IDLE = TmfStateValue.newValueInt(0);
-
- /** State value representing the running state */
- public static ITmfStateValue RUNNING = TmfStateValue.newValueInt(1);
-
- /**
- * Constructor
- *
- * @param trace
- * The trace to which this state provider is associated
- */
- public MyStateProvider(ITmfTrace trace) {
- super(trace, CtfTmfEvent.class, "Example"); //$NON-NLS-1$
- /*
- * The third parameter here is not important, it's only used to name a
- * thread internally.
- */
- }
-
- @Override
- public int getVersion() {
- /*
- * If the version of an existing file doesn't match the version supplied
- * in the provider, a rebuild of the history will be forced.
- */
- return 1;
- }
-
- @Override
- public MyStateProvider getNewInstance() {
- return new MyStateProvider(getTrace());
- }
-
- @Override
- protected void eventHandle(ITmfEvent ev) {
- /*
- * AbstractStateChangeInput should have already checked for the correct
- * class type.
- */
- CtfTmfEvent event = (CtfTmfEvent) ev;
-
- final long ts = event.getTimestamp().getValue();
- Integer nextTid = ((Long) event.getContent().getField("next_tid").getValue()).intValue();
-
- try {
-
- if (event.getEventName().equals("sched_switch")) {
- int quark = ss.getQuarkAbsoluteAndAdd("CPUs", String.valueOf(event.getCPU()), "Status");
- ITmfStateValue value;
- if (nextTid > 0) {
- value = RUNNING;
- } else {
- value = IDLE;
- }
- ss.modifyAttribute(ts, value, quark);
- }
-
- } catch (TimeRangeException e) {
- /*
- * This should not happen, since the timestamp comes from a trace
- * event.
- */
- throw new IllegalStateException(e);
- } catch (AttributeNotFoundException e) {
- /*
- * This should not happen either, since we're only accessing a quark
- * we just created.
- */
- throw new IllegalStateException(e);
- } catch (StateValueTypeException e) {
- /*
- * This wouldn't happen here, but could potentially happen if we try
- * to insert mismatching state value types in the same attribute.
- */
- e.printStackTrace();
- }
-
- }
-
-}
-</pre>
-
-=== Trace type definition ===
-
-<pre>
-import java.io.File;
-
-import org.eclipse.core.resources.IProject;
-import org.eclipse.core.runtime.IStatus;
-import org.eclipse.core.runtime.Status;
-import org.eclipse.linuxtools.tmf.core.ctfadaptor.CtfTmfTrace;
-import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateProvider;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
-import org.eclipse.linuxtools.tmf.core.statesystem.TmfStateSystemFactory;
-import org.eclipse.linuxtools.tmf.core.trace.TmfTraceManager;
-
-/**
- * Example of a custom trace type using a custom state provider.
- *
- * @author Alexandre Montplaisir
- */
-public class MyTraceType extends CtfTmfTrace {
-
- /** The file name of the history file */
- public final static String HISTORY_FILE_NAME = "mystatefile.ht";
-
- /** ID of the state system we will build */
- public static final String STATE_ID = "org.eclipse.linuxtools.lttng2.example";
-
- /**
- * Default constructor
- */
- public MyTraceType() {
- super();
- }
-
- @Override
- public IStatus validate(final IProject project, final String path) {
- /*
- * Add additional validation code here, and return a IStatus.ERROR if
- * validation fails.
- */
- return Status.OK_STATUS;
- }
-
- @Override
- protected void buildStateSystem() throws TmfTraceException {
- super.buildStateSystem();
-
- /* Build the custom state system for this trace */
- String directory = TmfTraceManager.getSupplementaryFileDir(this);
- final File htFile = new File(directory + HISTORY_FILE_NAME);
- final ITmfStateProvider htInput = new MyStateProvider(this);
-
- ITmfStateSystem ss = TmfStateSystemFactory.newFullHistory(htFile, htInput, false);
- fStateSystems.put(STATE_ID, ss);
- }
-
-}
-</pre>
-
-=== Query code ===
-
-<pre>
-import java.util.List;
-
-import org.eclipse.linuxtools.tmf.core.exceptions.AttributeNotFoundException;
-import org.eclipse.linuxtools.tmf.core.exceptions.StateSystemDisposedException;
-import org.eclipse.linuxtools.tmf.core.exceptions.TimeRangeException;
-import org.eclipse.linuxtools.tmf.core.interval.ITmfStateInterval;
-import org.eclipse.linuxtools.tmf.core.statesystem.ITmfStateSystem;
-import org.eclipse.linuxtools.tmf.core.statevalue.ITmfStateValue;
-import org.eclipse.linuxtools.tmf.core.trace.ITmfTrace;
-
-/**
- * Class showing examples of state system queries.
- *
- * @author Alexandre Montplaisir
- */
-public class QueryExample {
-
- private final ITmfStateSystem ss;
-
- /**
- * Constructor
- *
- * @param trace
- * Trace that this "view" will display.
- */
- public QueryExample(ITmfTrace trace) {
- ss = trace.getStateSystems().get(MyTraceType.STATE_ID);
- }
-
- /**
- * Example method of querying one attribute in the state system.
- *
- * We pass it a cpu and a timestamp, and it returns us if that cpu was
- * executing a process (true/false) at that time.
- *
- * @param cpu
- * The CPU to check
- * @param timestamp
- * The timestamp of the query
- * @return True if the CPU was running, false otherwise
- */
- public boolean cpuIsRunning(int cpu, long timestamp) {
- try {
- int quark = ss.getQuarkAbsolute("CPUs", String.valueOf(cpu), "Status");
- ITmfStateValue value = ss.querySingleState(timestamp, quark).getStateValue();
-
- if (value.equals(MyStateProvider.RUNNING)) {
- return true;
- }
-
- /*
- * Since at this level we have no guarantee on the contents of the state
- * system, it's important to handle these cases correctly.
- */
- } catch (AttributeNotFoundException e) {
- /*
- * Handle the case where the attribute does not exist in the state
- * system (no CPU with this number, etc.)
- */
- ...
- } catch (TimeRangeException e) {
- /*
- * Handle the case where 'timestamp' is outside of the range of the
- * history.
- */
- ...
- } catch (StateSystemDisposedException e) {
- /*
- * Handle the case where the state system is being disposed. If this
- * happens, it's normally when shutting down, so the view can just
- * return immediately and wait it out.
- */
- }
- return false;
- }
-
-
- /**
- * Example method of using a full query.
- *
- * We pass it a timestamp, and it returns us how many CPUs were executing a
- * process at that moment.
- *
- * @param timestamp
- * The target timestamp
- * @return The amount of CPUs that were running at that time
- */
- public int getNbRunningCpus(long timestamp) {
- int count = 0;
-
- try {
- /* Get the list of the quarks we are interested in. */
- List<Integer> quarks = ss.getQuarks("CPUs", "*", "Status");
-
- /*
- * Get the full state at our target timestamp (it's better than
- * doing an arbitrary number of single queries).
- */
- List<ITmfStateInterval> state = ss.queryFullState(timestamp);
-
- /* Look at the value of the state for each quark */
- for (Integer quark : quarks) {
- ITmfStateValue value = state.get(quark).getStateValue();
- if (value.equals(MyStateProvider.RUNNING)) {
- count++;
- }
- }
-
- } catch (TimeRangeException e) {
- /*
- * Handle the case where 'timestamp' is outside of the range of the
- * history.
- */
- ...
- } catch (StateSystemDisposedException e) {
- /* Handle the case where the state system is being disposed. */
- ...
- }
- return count;
- }
-}
-</pre>
-
-== Mipmap feature ==
-
-The mipmap feature allows attributes to be inserted into the state system with
-additional computations performed to automatically store sub-attributes that
-can later be used for statistical operations. The mipmap has a resolution which
-represents the number of state attribute changes that are used to compute the
-value at the next mipmap level.
-
-The supported mipmap features are: max, min, and average. Each one of these
-features requires that the base attribute be a numerical state value (int, long
-or double). An attribute can be mipmapped for one or more of the features at
-the same time.
-
-To use a mipmapped attribute in queries, call the corresponding methods of the
-static class [[#State System Operations | TmfStateSystemOperations]].
-
-=== AbstractTmfMipmapStateProvider ===
-
-AbstractTmfMipmapStateProvider is an abstract provider class that allows adding
-features to a specific attribute into a mipmap tree. It extends AbstractTmfStateProvider.
-
-If a provider wants to add mipmapped attributes to its tree, it must extend
-AbstractTmfMipmapStateProvider and call modifyMipmapAttribute() in the event
-handler, specifying one or more mipmap features to compute. Then the structure
-of the attribute tree will be :
-
-<pre>
-|- <attribute>
-| |- <mipmapFeature> (min/max/avg)
-| | |- 1
-| | |- 2
-| | |- 3
-| | ...
-| | |- n (maximum mipmap level)
-| |- <mipmapFeature> (min/max/avg)
-| | |- 1
-| | |- 2
-| | |- 3
-| | ...
-| | |- n (maximum mipmap level)
-| ...
-</pre>
-
-= UML2 Sequence Diagram Framework =
-
-The purpose of the UML2 Sequence Diagram Framework of TMF is to provide a framework for generation of UML2 sequence diagrams. It provides
-*UML2 Sequence diagram drawing capabilities (i.e. lifelines, messages, activations, object creation and deletion)
-*a generic, re-usable Sequence Diagram View
-*Eclipse Extension Point for the creation of sequence diagrams
-*callback hooks for searching and filtering within the Sequence Diagram View
-*scalability<br>
-The following chapters describe the Sequence Diagram Framework as well as a reference implementation and its usage.
-
-== TMF UML2 Sequence Diagram Extensions ==
-
-In the UML2 Sequence Diagram Framework an Eclipse extension point is defined so that other plug-ins can contribute code to create sequence diagram.
-
-'''Identifier''': org.eclipse.linuxtools.tmf.ui.uml2SDLoader<br>
-'''Since''': 1.0<br>
-'''Description''': This extension point aims to list and connect any UML2 Sequence Diagram loader.<br>
-'''Configuration Markup''':<br>
-
-<pre>
-<!ELEMENT extension (uml2SDLoader)+>
-<!ATTLIST extension
-point CDATA #REQUIRED
-id CDATA #IMPLIED
-name CDATA #IMPLIED
->
-</pre>
-
-*point - A fully qualified identifier of the target extension point.
-*id - An optional identifier of the extension instance.
-*name - An optional name of the extension instance.
-
-<pre>
-<!ELEMENT uml2SDLoader EMPTY>
-<!ATTLIST uml2SDLoader
-id CDATA #REQUIRED
-name CDATA #REQUIRED
-class CDATA #REQUIRED
-view CDATA #REQUIRED
-default (true | false)
-</pre>
-
-*id - A unique identifier for this uml2SDLoader. This is not mandatory as long as the id attribute cannot be retrieved by the provider plug-in. The class attribute is the one on which the underlying algorithm relies.
-*name - An name of the extension instance.
-*class - The implementation of this UML2 SD viewer loader. The class must implement org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader.
-*view - The view ID of the view that this loader aims to populate. Either org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView itself or a extension of org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView.
-*default - Set to true to make this loader the default one for the view; in case of several default loaders, first one coming from extensions list is taken.
-
-
-== Management of the Extension Point ==
-
-The TMF UI plug-in is responsible for evaluating each contribution to the extension point.
-<br>
-<br>
-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]])
-
-== Sequence Diagram View ==
-
-For this extension point a Sequence Diagram View has to be defined as well. The Sequence Diagram View class implementation is provided by the plug-in ''org.eclipse.linuxtools.tmf.ui'' (''org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView'') and can be used as is or can also be sub-classed. For that, a view extension has to be added to the ''plugin.xml''.
-
-=== Supported Widgets ===
-
-The loader class provides a frame containing all the UML2 widgets to be displayed. The following widgets exist:
-
-*Lifeline
-*Activation
-*Synchronous Message
-*Asynchronous Message
-*Synchronous Message Return
-*Asynchronous Message Return
-*Stop
-
-For a lifeline, a category can be defined. The lifeline category defines icons, which are displayed in the lifeline header.
-
-=== Zooming ===
-
-The Sequence Diagram View allows the user to zoom in, zoom out and reset the zoom factor.
-
-=== Printing ===
-
-It is possible to print the whole sequence diagram as well as part of it.
-
-=== Key Bindings ===
-
-*SHIFT+ALT+ARROW-DOWN - to scroll down within sequence diagram one view page at a time
-*SHIFT+ALT+ARROW-UP - to scroll up within sequence diagram one view page at a time
-*SHIFT+ALT+ARROW-RIGHT - to scroll right within sequence diagram one view page at a time
-*SHIFT+ALT+ARROW-LEFT - to scroll left within sequence diagram one view page at a time
-*SHIFT+ALT+ARROW-HOME - to jump to the beginning of the selected message if not already visible in page
-*SHIFT+ALT+ARROW-END - to jump to the end of the selected message if not already visible in page
-*CTRL+F - to open find dialog if either the basic or extended find provider is defined (see [[#Using the Find Provider Interface | Using the Find Provider Interface]])
-*CTRL+P - to open print dialog
-
-=== Preferences ===
-
-The UML2 Sequence Diagram Framework provides preferences to customize the appearance of the Sequence Diagram View. The color of all widgets and text as well as the fonts of the text of all widget can be adjust. Amongst others the default lifeline width can be alternated. To change preferences select '''Windows->Preferences->Tracing->UML2 Sequence Diagrams'''. The following preference page will show:<br>
-[[Image:images/SeqDiagramPref.png]] <br>
-After changing the preferences select '''OK'''.
-
-=== Callback hooks ===
-
-The Sequence Diagram View provides several callback hooks so that extension can provide application specific functionality. The following interfaces can be provided:
-* Basic find provider or extended find Provider<br> For finding within the sequence diagram
-* Basic filter provider and extended Filter Provider<br> For filtering within the sequnce diagram.
-* Basic paging provider or advanced paging provider<br> For scalability reasons, used to limit number of displayed messages
-* Properies provider<br> To provide properties of selected elements
-* Collapse provider <br> To collapse areas of the sequence diagram
-
-== Tutorial ==
-
-This tutorial describes how to create a UML2 Sequence Diagram Loader extension and use this loader in the in Eclipse.
-
-=== Prerequisites ===
-
-The tutorial is based on Eclipse 4.4 (Eclipse Luna) and TMF 3.0.0.
-
-=== Creating an Eclipse UI Plug-in ===
-
-To create a new project with name org.eclipse.linuxtools.tmf.sample.ui select '''File -> New -> Project -> Plug-in Development -> Plug-in Project'''. <br>
-[[Image:images/Screenshot-NewPlug-inProject1.png]]<br>
-
-[[Image:images/Screenshot-NewPlug-inProject2.png]]<br>
-
-[[Image:images/Screenshot-NewPlug-inProject3.png]]<br>
-
-=== Creating a Sequence Diagram View ===
-
-To open the plug-in manifest, double-click on the MANIFEST.MF file. <br>
-[[Image:images/SelectManifest.png]]<br>
-
-Change to the Dependencies tab and select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-ins ''org.eclipse.linuxtools.tmf.ui'' and ''org.eclipse.linuxtools.tmf.core'' and then press '''OK'''<br>
-[[Image:images/AddDependencyTmfUi.png]]<br>
-
-Change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the view extension ''org.eclipse.ui.views'' and press '''Finish'''.<br>
-[[Image:images/AddViewExtension1.png]]<br>
-
-To create a Sequence Diagram View, click the right mouse button. Then select '''New -> view'''<br>
-[[Image:images/AddViewExtension2.png]]<br>
-
-A new view entry has been created. Fill in the fields ''id'', ''name'' and ''class''. Note that for ''class'' the SD view implementation (''org.eclipse.linuxtools.tmf.ui.views.SDView'') of the TMF UI plug-in is used.<br>
-[[Image:images/FillSampleSeqDiagram.png]]<br>
-
-The view is prepared. Run the Example. To launch the an Eclipse Application select the ''Overview'' tab and click on '''Launch an Eclipse Application'''<br>
-[[Image:images/RunEclipseApplication.png]]<br>
-
-A new Eclipse application window will show. In the new window go to '''Windows -> Show View -> Other... -> Other -> Sample Sequence Diagram'''.<br>
-[[Image:images/ShowViewOther.png]]<br>
-
-The Sequence Diagram View will open with an blank page.<br>
-[[Image:images/BlankSampleSeqDiagram.png]]<br>
-
-Close the Example Application.
-
-=== Defining the uml2SDLoader Extension ===
-
-After defining the Sequence Diagram View it's time to create the ''uml2SDLoader'' Extension. <br>
-
-Before doing that add a dependency to TMF. For that select '''Add...''' of the ''Required Plug-ins'' section. A new dialog box will open. Next find plug-in ''org.eclipse.linuxtools.tmf'' and press '''OK'''<br>
-[[Image:images/AddDependencyTmf.png]]<br>
-
-To create the loader extension, change to the Extensions tab and select '''Add...''' of the ''All Extension'' section. A new dialog box will open. Find the extension ''org.eclipse.linuxtools.tmf.ui.uml2SDLoader'' and press '''Finish'''.<br>
-[[Image:images/AddTmfUml2SDLoader.png]]<br>
-
-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>
-[[Image:images/FillSampleLoader.png]]<br>
-
-Then click on ''class'' (see above) to open the new class dialog box. Fill in the relevant fields and select '''Finish'''. <br>
-[[Image:images/NewSampleLoaderClass.png]]<br>
-
-A new Java class will be created which implements the interface ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader''.<br>
-
-<pre>
-package org.eclipse.linuxtools.tmf.sample.ui;
-
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
-
-public class SampleLoader implements IUml2SDLoader {
-
- public SampleLoader() {
- // TODO Auto-generated constructor stub
- }
-
- @Override
- public void dispose() {
- // TODO Auto-generated method stub
-
- }
-
- @Override
- public String getTitleString() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public void setViewer(SDView arg0) {
- // TODO Auto-generated method stub
-
- }
-</pre>
-
-=== Implementing the Loader Class ===
-
-Next is to implement the methods of the IUml2SDLoader interface method. The following code snippet shows how to create the major sequence diagram elements. Please note that no time information is stored.<br>
-
-<pre>
-package org.eclipse.linuxtools.tmf.sample.ui;
-
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.SDView;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessage;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.AsyncMessageReturn;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.ExecutionOccurrence;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Frame;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Lifeline;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.Stop;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessage;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.core.SyncMessageReturn;
-import org.eclipse.linuxtools.tmf.ui.views.uml2sd.load.IUml2SDLoader;
-
-public class SampleLoader implements IUml2SDLoader {
-
- private SDView fSdView;
-
- public SampleLoader() {
- }
-
- @Override
- public void dispose() {
- }
-
- @Override
- public String getTitleString() {
- return "Sample Diagram";
- }
-
- @Override
- public void setViewer(SDView arg0) {
- fSdView = arg0;
- createFrame();
- }
-
- private void createFrame() {
-
- Frame testFrame = new Frame();
- testFrame.setName("Sample Frame");
-
- /*
- * Create lifelines
- */
-
- Lifeline lifeLine1 = new Lifeline();
- lifeLine1.setName("Object1");
- testFrame.addLifeLine(lifeLine1);
-
- Lifeline lifeLine2 = new Lifeline();
- lifeLine2.setName("Object2");
- testFrame.addLifeLine(lifeLine2);
-
-
- /*
- * Create Sync Message
- */
- // Get new occurrence on lifelines
- lifeLine1.getNewEventOccurrence();
-
- // Get Sync message instances
- SyncMessage start = new SyncMessage();
- start.setName("Start");
- start.setEndLifeline(lifeLine1);
- testFrame.addMessage(start);
-
- /*
- * Create Sync Message
- */
- // Get new occurrence on lifelines
- lifeLine1.getNewEventOccurrence();
- lifeLine2.getNewEventOccurrence();
-
- // Get Sync message instances
- SyncMessage syn1 = new SyncMessage();
- syn1.setName("Sync Message 1");
- syn1.setStartLifeline(lifeLine1);
- syn1.setEndLifeline(lifeLine2);
- testFrame.addMessage(syn1);
-
- /*
- * Create corresponding Sync Message Return
- */
-
- // Get new occurrence on lifelines
- lifeLine1.getNewEventOccurrence();
- lifeLine2.getNewEventOccurrence();
-
- SyncMessageReturn synReturn1 = new SyncMessageReturn();
- synReturn1.setName("Sync Message Return 1");
- synReturn1.setStartLifeline(lifeLine2);
- synReturn1.setEndLifeline(lifeLine1);
- synReturn1.setMessage(syn1);
- testFrame.addMessage(synReturn1);
-
- /*
- * Create Activations (Execution Occurrence)
- */
- ExecutionOccurrence occ1 = new ExecutionOccurrence();
- occ1.setStartOccurrence(start.getEventOccurrence());
- occ1.setEndOccurrence(synReturn1.getEventOccurrence());
- lifeLine1.addExecution(occ1);
- occ1.setName("Activation 1");
-
- ExecutionOccurrence occ2 = new ExecutionOccurrence();
- occ2.setStartOccurrence(syn1.getEventOccurrence());
- occ2.setEndOccurrence(synReturn1.getEventOccurrence());
- lifeLine2.addExecution(occ2);
- occ2.setName("Activation 2");
-
- /*
- * Create Sync Message
- */
- // Get new occurrence on lifelines
- lifeLine1.getNewEventOccurrence();
- lifeLine2.getNewEventOccurrence();
-
- // Get Sync message instances
- AsyncMessage asyn1 = new AsyncMessage();
- asyn1.setName("Async Message 1");
- asyn1.setStartLifeline(lifeLine1);
- asyn1.setEndLifeline(lifeLine2);
- testFrame.addMessage(asyn1);
-
- /*
- * Create corresponding Sync Message Return
- */
-
- // Get new occurrence on lifelines
- lifeLine1.getNewEventOccurrence();
- lifeLine2.getNewEventOccurrence();
-
- AsyncMessageReturn asynReturn1 = new AsyncMessageReturn();
- asynReturn1.setName("Async Message Return 1");
- asynReturn1.setStartLifeline(lifeLine2);
- asynReturn1.setEndLifeline(lifeLine1);
- asynReturn1.setMessage(asyn1);
- testFrame.addMessage(asynReturn1);
-
- /*
- * Create a note
- */
-
- // Get new occurrence on lifelines
- lifeLine1.getNewEventOccurrence();
-
- EllipsisMessage info = new EllipsisMessage();
- info.setName("Object deletion");
- info.setStartLifeline(lifeLine2);
- testFrame.addNode(info);
-
- /*
- * Create a Stop
- */
- Stop stop = new Stop();
- stop.setLifeline(lifeLine2);
- stop.setEventOccurrence(lifeLine2.getNewEventOccurrence());
- lifeLine2.addNode(stop);
-
- fSdView.setFrame(testFrame);
- }
-}
-</pre>
-
-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>
-[[Image:images/SampleDiagram1.png]] <br>
-
-=== Adding time information ===
-
-To add time information in sequence diagram the timestamp has to be set for each message. The sequence diagram framework uses the ''TmfTimestamp'' class of plug-in ''org.eclipse.linuxtools.tmf.core''. Use ''setTime()'' on each message ''SyncMessage'' since start and end time are the same. For each ''AsyncMessage'' set start and end time separately by using methods ''setStartTime'' and ''setEndTime''. For example: <br>
-
-<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));
- //...
- }
-</pre>
-
-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>
-
-[[Image:images/SampleDiagramTimeComp.png]] <br>
-
-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.
-
-[[Image:images/SampleDiagramSyncMessage.png]] <br>
-[[Image:images/SampleDiagramAsyncMessage.png]] <br>
-
-To see the time elapsed between 2 messages, select one message and hover over a second message. A tooltip will show with the delta in time. Note if the second message is before the first then a negative delta is displayed. Note that for ''AsyncMessage'' the end time is used for the delta calculation.<br>
-[[Image:images/SampleDiagramMessageDelta.png]] <br>
-
-=== Default Coolbar and Menu Items ===
-
-The Sequence Diagram View comes with default coolbar and menu items. By default, each sequence diagram shows the following actions:
-* Zoom in
-* Zoom out
-* Reset Zoom Factor
-* Selection
-* Configure Min Max (drop-down menu only)
-* Navigation -> Show the node end (drop-down menu only)
-* Navigation -> Show the node start (drop-down menu only)
-
-[[Image:images/DefaultCoolbarMenu.png]]<br>
-
-=== Implementing Optional Callbacks ===
-
-The following chapters describe how to use all supported provider interfaces.
-
-==== Using the Paging Provider Interface ====
-
-For scalability reasons, the paging provider interfaces exists to limit the number of messages displayed in the Sequence Diagram View at a time. For that, two interfaces exist, the basic paging provider and the advanced paging provider. When using the basic paging interface, actions for traversing page by page through the sequence diagram of a trace will be provided.
-<br>
-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.
-
-<pre>
-public class SampleLoader implements IUml2SDLoader, ISDPagingProvider {
- //...
- private page = 0;
-
- @Override
- public void dispose() {
- if (fSdView != null) {
- fSdView.resetProviders();
- }
- }
-
- @Override
- public void setViewer(SDView arg0) {
- fSdView = arg0;
- fSdView.setSDPagingProvider(this);
- createFrame();
- }
-
- private void createSecondFrame() {
- Frame testFrame = new Frame();
- testFrame.setName("SecondFrame");
- Lifeline lifeline = new Lifeline();
- lifeline.setName("LifeLine 0");
- testFrame.addLifeLine(lifeline);
- lifeline = new Lifeline();
- lifeline.setName("LifeLine 1");
- testFrame.addLifeLine(lifeline);
- for (int i = 1; i < 5; i++) {
- SyncMessage message = new SyncMessage();
- message.autoSetStartLifeline(testFrame.getLifeline(0));
- message.autoSetEndLifeline(testFrame.getLifeline(0));
- message.setName((new StringBuilder("Message ")).append(i).toString());
- testFrame.addMessage(message);
-
- SyncMessageReturn messageReturn = new SyncMessageReturn();
- messageReturn.autoSetStartLifeline(testFrame.getLifeline(0));
- messageReturn.autoSetEndLifeline(testFrame.getLifeline(0));
-
- testFrame.addMessage(messageReturn);
- messageReturn.setName((new StringBuilder("Message return ")).append(i).toString());
- ExecutionOccurrence occ = new ExecutionOccurrence();
- occ.setStartOccurrence(testFrame.getSyncMessage(i - 1).getEventOccurrence());
- occ.setEndOccurrence(testFrame.getSyncMessageReturn(i - 1).getEventOccurrence());
- testFrame.getLifeline(0).addExecution(occ);
- }
- fSdView.setFrame(testFrame);
- }
-
- @Override
- public boolean hasNextPage() {
- return page == 0;
- }
-
- @Override
- public boolean hasPrevPage() {
- return page == 1;
- }
-
- @Override
- public void nextPage() {
- page = 1;
- createSecondFrame();
- }
-
- @Override
- public void prevPage() {
- page = 0;
- createFrame();
- }
-
- @Override
- public void firstPage() {
- page = 0;
- createFrame();
- }
-
- @Override
- public void lastPage() {
- page = 1;
- createSecondFrame();
- }
- //...
-}
-
-</pre>
-
-When running the example application, new actions will be shown in the coolbar and the coolbar menu. <br>
-
-[[Image:images/PageProviderAdded.png]]
-
-<br><br>
-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.
-<br>
-
-==== Using the Find Provider Interface ====
-
-For finding nodes in a sequence diagram two interfaces exists. One for basic finding and one for extended finding. The basic find comes with a dialog box for entering find criteria as regular expressions. This find criteria can be used to execute the find. Find criteria a persisted in the Eclipse workspace.
-<br>
-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.
-<br>
-Only on at a time can be active. If the extended find provder is defined it obsoletes the basic find provider.
-<br>
-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.
-
-<pre>
-public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider {
-
- //...
- @Override
- public void dispose() {
- if (fSdView != null) {
- fSdView.resetProviders();
- }
- }
-
- @Override
- public void setViewer(SDView arg0) {
- fSdView = arg0;
- fSdView.setSDPagingProvider(this);
- fSdView.setSDFindProvider(this);
- createFrame();
- }
-
- @Override
- public boolean isNodeSupported(int nodeType) {
- switch (nodeType) {
- case ISDGraphNodeSupporter.LIFELINE:
- case ISDGraphNodeSupporter.SYNCMESSAGE:
- return true;
-
- default:
- break;
- }
- return false;
- }
-
- @Override
- public String getNodeName(int nodeType, String loaderClassName) {
- switch (nodeType) {
- case ISDGraphNodeSupporter.LIFELINE:
- return "Lifeline";
- case ISDGraphNodeSupporter.SYNCMESSAGE:
- return "Sync Message";
- }
- return "";
- }
-
- @Override
- public boolean find(Criteria criteria) {
- Frame frame = fSdView.getFrame();
- if (criteria.isLifeLineSelected()) {
- for (int i = 0; i < frame.lifeLinesCount(); i++) {
- if (criteria.matches(frame.getLifeline(i).getName())) {
- fSdView.getSDWidget().moveTo(frame.getLifeline(i));
- return true;
- }
- }
- }
- if (criteria.isSyncMessageSelected()) {
- for (int i = 0; i < frame.syncMessageCount(); i++) {
- if (criteria.matches(frame.getSyncMessage(i).getName())) {
- fSdView.getSDWidget().moveTo(frame.getSyncMessage(i));
- return true;
- }
- }
- }
- return false;
- }
-
- @Override
- public void cancel() {
- // reset find parameters
- }
- //...
-}
-</pre>
-
-When running the example application, the find action will be shown in the coolbar and the coolbar menu. <br>
-[[Image:images/FindProviderAdded.png]]
-
-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>
-[[Image:images/FindDialog.png]]<br>
-
-Note that the find dialog will be opened by typing the key shortcut CRTL+F.
-
-==== Using the Filter Provider Interface ====
-
-For filtering of sequence diagram elements two interfaces exist. One basic for filtering and one for extended filtering. The basic filtering comes with two dialog for entering filter criteria as regular expressions and one for selecting the filter to be used. Multiple filters can be active at a time. Filter criteria are persisted in the Eclipse workspace.
-<br>
-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>
-Note that no example implementation of ''filter()'' is provided.
-<br>
-
-<pre>
-public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider {
-
- //...
- @Override
- public void dispose() {
- if (fSdView != null) {
- fSdView.resetProviders();
- }
- }
-
- @Override
- public void setViewer(SDView arg0) {
- fSdView = arg0;
- fSdView.setSDPagingProvider(this);
- fSdView.setSDFindProvider(this);
- fSdView.setSDFilterProvider(this);
- createFrame();
- }
-
- @Override
- public boolean filter(List<?> list) {
- return false;
- }
- //...
-}
-</pre>
-
-When running the example application, the filter action will be shown in the coolbar menu. <br>
-[[Image:images/HidePatternsMenuItem.png]]
-
-To filter select the '''Hide Patterns...''' of the coolbar menu. A new dialog box will open. <br>
-[[Image:images/DialogHidePatterns.png]]
-
-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>
-[[Image:images/DialogHidePatterns.png]] <br>
-
-Now back at the Hide Pattern dialog. Select one or more filter and select '''OK'''.
-
-To use the extended filter provider, the interface ''ISDExtendedFilterProvider'' has to be implemented. It will provide a ''org.eclipse.jface.action.Action'' class containing the actual filter handling and filter algorithm.
-
-==== Using the Extended Action Bar Provider Interface ====
-
-The extended action bar provider can be used to add customized actions to the Sequence Diagram View.
-To use the extended action bar provider, first the interface method of the interface ''ISDExtendedActionBarProvider'' has to be implemented by a class. Typically, this is implemented in the loader class. Add the ''ISDExtendedActionBarProvider'' to the list of implemented interfaces, implement the method ''supplementCoolbarContent()'' and set the provider in the ''setViewer()'' method as well as remove the provider in the ''dispose()'' method of the loader class. <br>
-
-<pre>
-public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider {
- //...
-
- @Override
- public void dispose() {
- if (fSdView != null) {
- fSdView.resetProviders();
- }
- }
-
- @Override
- public void setViewer(SDView arg0) {
- fSdView = arg0;
- fSdView.setSDPagingProvider(this);
- fSdView.setSDFindProvider(this);
- fSdView.setSDFilterProvider(this);
- fSdView.setSDExtendedActionBarProvider(this);
- createFrame();
- }
-
- @Override
- public void supplementCoolbarContent(IActionBars iactionbars) {
- Action action = new Action("Refresh") {
- @Override
- public void run() {
- System.out.println("Refreshing...");
- }
- };
- iactionbars.getMenuManager().add(action);
- iactionbars.getToolBarManager().add(action);
- }
- //...
-}
-</pre>
-
-When running the example application, all new actions will be added to the coolbar and coolbar menu according to the implementation of ''supplementCoolbarContent()''<br>.
-For the example above the coolbar and coolbar menu will look as follows.
-
-[[Image:images/SupplCoolbar.png]]
-
-==== Using the Properties Provider Interface====
-
-This interface can be used to provide property information. A property provider which returns an ''IPropertyPageSheet'' (see ''org.eclipse.ui.views'') has to be implemented and set in the Sequence Diagram View. <br>
-
-To use the property provider, first the interface method of the ''ISDPropertiesProvider'' has to be implemented by a class. Typically, this is implemented in the loader class. Add the ''ISDPropertiesProvider'' to the list of implemented interfaces, implement the method ''getPropertySheetEntry()'' and set the provider in the ''setViewer()'' method as well as remove the provider in the ''dispose()'' method of the loader class. Please note that no example is provided here.
-
-Please refer to the following Eclipse articles for more information about properties and tabed properties.
-*[http://www.eclipse.org/articles/Article-Properties-View/properties-view.html | Take control of your properties]
-*[http://www.eclipse.org/articles/Article-Tabbed-Properties/tabbed_properties_view.html | The Eclipse Tabbed Properties View]
-
-==== Using the Collapse Provider Interface ====
-
-This interface can be used to define a provider which responsibility is to collapse two selected lifelines. This can be used to hide a pair of lifelines.
-
-To use the collapse provider, first the interface method of the ''ISDCollapseProvider'' has to be implemented by a class. Typically, this is implemented in the loader class. Add the ISDCollapseProvider to the list of implemented interfaces, implement the method ''collapseTwoLifelines()'' and set the provider in the ''setViewer()'' method as well as remove the provider in the ''dispose()'' method of the loader class. Please note that no example is provided here.
-
-==== Using the Selection Provider Service ====
-
-The Sequence Diagram View comes with a build in selection provider service. To this service listeners can be added. To use the selection provider service, the interface ''ISelectionListener'' of plug-in ''org.eclipse.ui'' has to implemented. Typically this is implemented in loader class. Firstly, add the ''ISelectionListener'' interface to the list of implemented interfaces, implement the method ''selectionChanged()'' and set the listener in method ''setViewer()'' as well as remove the listener in the ''dispose()'' method of the loader class.
-
-<pre>
-public class SampleLoader implements IUml2SDLoader, ISDPagingProvider, ISDFindProvider, ISDFilterProvider, ISDExtendedActionBarProvider, ISelectionListener {
-
- //...
- @Override
- public void dispose() {
- if (fSdView != null) {
- PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().removePostSelectionListener(this);
- fSdView.resetProviders();
- }
- }
-
- @Override
- public String getTitleString() {
- return "Sample Diagram";
- }
-
- @Override
- public void setViewer(SDView arg0) {
- fSdView = arg0;
- PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().addPostSelectionListener(this);
- fSdView.setSDPagingProvider(this);
- fSdView.setSDFindProvider(this);
- fSdView.setSDFilterProvider(this);
- fSdView.setSDExtendedActionBarProvider(this);
-
- createFrame();
- }
-
- @Override
- public void selectionChanged(IWorkbenchPart part, ISelection selection) {
- ISelection sel = PlatformUI.getWorkbench().getActiveWorkbenchWindow().getSelectionService().getSelection();
- if (sel != null && (sel instanceof StructuredSelection)) {
- StructuredSelection stSel = (StructuredSelection) sel;
- if (stSel.getFirstElement() instanceof BaseMessage) {
- BaseMessage syncMsg = ((BaseMessage) stSel.getFirstElement());
- System.out.println("Message '" + syncMsg.getName() + "' selected.");
- }
- }
- }
-
- //...
-}
-</pre>
-
-=== Printing a Sequence Diagram ===
-
-To print a the whole sequence diagram or only parts of it, select the Sequence Diagram View and select '''File -> Print...''' or type the key combination ''CTRL+P''. A new print dialog will open. <br>
-
-[[Image:images/PrintDialog.png]] <br>
-
-Fill in all the relevant information, select '''Printer...''' to choose the printer and the press '''OK'''.
-
-=== Using one Sequence Diagram View with Multiple Loaders ===
-
-A Sequence Diagram View definition can be used with multiple sequence diagram loaders. However, the active loader to be used when opening the view has to be set. For this define an Eclipse action or command and assign the current loader to the view. Here is a code snippet for that:
-
-<pre>
-public class OpenSDView extends AbstractHandler {
- @Override
- public Object execute(ExecutionEvent event) throws ExecutionException {
- try {
- IWorkbenchPage persp = TmfUiPlugin.getDefault().getWorkbench().getActiveWorkbenchWindow().getActivePage();
- SDView view = (SDView) persp.showView("org.eclipse.linuxtools.ust.examples.ui.componentinteraction");
- LoadersManager.getLoadersManager().createLoader("org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl.TmfUml2SDSyncLoader", view);
- } catch (PartInitException e) {
- throw new ExecutionException("PartInitException caught: ", e);
- }
- return null;
- }
-}
-</pre>
-
-=== Downloading the Tutorial ===
-
-Use the following link to download the source code of the tutorial [http://wiki.eclipse.org/images/e/e6/SamplePlugin.zip Plug-in of Tutorial].
-
-== Integration of Tracing and Monitoring Framework with Sequence Diagram Framework ==
-
-In the previous sections the Sequence Diagram Framework has been described and a tutorial was provided. In the following sections the integration of the Sequence Diagram Framework with other features of TMF will be described. Together it is a powerful framework to analyze and visualize content of traces. The integration is explained using the reference implementation of a UML2 sequence diagram loader which part of the TMF UI delivery. The reference implementation can be used as is, can be sub-classed or simply be an example for other sequence diagram loaders to be implemented.
-
-=== Reference Implementation ===
-
-A Sequence Diagram View Extension is defined in the plug-in TMF UI as well as a uml2SDLoader Extension with the reference loader.
-
-[[Image:images/ReferenceExtensions.png]]
-
-=== Used Sequence Diagram Features ===
-
-Besides the default features of the Sequence Diagram Framework, the reference implementation uses the following additional features:
-*Advanced paging
-*Basic finding
-*Basic filtering
-*Selection Service
-
-==== Advanced paging ====
-
-The reference loader implements the interface ''ISDAdvancedPagingProvider'' interface. Please refer to section [[#Using the Paging Provider Interface | Using the Paging Provider Interface]] for more details about the advanced paging feature.
-
-==== Basic finding ====
-
-The reference loader implements the interface ''ISDFindProvider'' interface. The user can search for ''Lifelines'' and ''Interactions''. The find is done across pages. If the expression to match is not on the current page a new thread is started to search on other pages. If expression is found the corresponding page is shown as well as the searched item is displayed. If not found then a message is displayed in the ''Progress View'' of Eclipse. Please refer to section [[#Using the Find Provider Interface | Using the Find Provider Interface]] for more details about the basic find feature.
-
-==== Basic filtering ====
-
-The reference loader implements the interface ''ISDFilterProvider'' interface. The user can filter on ''Lifelines'' and ''Interactions''. Please refer to section [[#Using the Filter Provider Interface | Using the Filter Provider Interface]] for more details about the basic filter feature.
-
-==== Selection Service ====
-
-The reference loader implements the interface ''ISelectionListener'' interface. When an interaction is selected a ''TmfTimeSynchSignal'' is broadcast (see [[#TMF Signal Framework | 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 .
-
-=== Used TMF Features ===
-
-The reference implementation uses the following features of TMF:
-*TMF Experiment and Trace for accessing traces
-*Event Request Framework to request TMF events from the experiment and respective traces
-*Signal Framework for broadcasting and receiving TMF signals for synchronization purposes
-
-==== TMF Experiment and Trace for accessing traces ====
-
-The reference loader uses TMF Experiments to access traces and to request data from the traces.
-
-==== TMF Event Request Framework ====
-
-The reference loader use the TMF Event Request Framework to request events from the experiment and its traces.
-
-When opening a traces (which is triggered by signal ''TmfExperimentSelected'') or when opening the Sequence Diagram View after a trace had been opened previously, a TMF background request is initiated to index the trace and to fill in the first page of the sequence diagram. The purpose of the indexing is to store time ranges for pages with 10000 messages per page. This allows quickly to move to certain pages in a trace without having to re-parse from the beginning. The request is called indexing request.
-
-When switching pages, the a TMF foreground event request is initiated to retrieve the corresponding events from the experiment. It uses the time range stored in the index for the respective page.
-
-A third type of event request is issued for finding specific data across pages.
-
-==== TMF Signal Framework ====
-
-The reference loader extends the class ''TmfComponent''. By doing that the loader is registered as a TMF signal handler for sending and receiving TMF signals. The loader implements signal handlers for the following TMF signals:
-*''TmfTraceSelectedSignal''
-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.
-*''TmfTraceClosedSignal''
-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.
-*''TmfTimeSynchSignal''
-This signal is used to indicate that a new time or time range has been selected. It contains a begin and end time. If a single time is selected then the begin and end time are the same. When receiving this signal the corresponding message matching the begin time is selected in the Sequence Diagram View. If necessary, the page is changed.
-*''TmfRangeSynchSignal''
-This signal indicates that a new time range is in focus. When receiving this signal the loader loads the page which corresponds to the start time of the time range signal. The message with the start time will be in focus.
-
-Besides acting on receiving signals, the reference loader is also sending signals. A ''TmfTimeSynchSignal'' is broadcasted with the 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''.
-
-=== Supported Traces ===
-
-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>
-
-Note that combined traces of multiple components, that contain the trace information about the same interactions are not supported in the reference implementation!
-
-=== Trace Format ===
-
-The reference implementation in class ''TmfUml2SDSyncLoader'' in package ''org.eclipse.linuxtools.tmf.ui.views.uml2sd.impl'' analyzes events from type ''ITmfEvent'' and creates events type ''ITmfSyncSequenceDiagramEvent'' if the ''ITmfEvent'' contains all relevant information information. The parsing algorithm looks like as follows:
-
-<pre>
- /**
- * @param tmfEvent Event to parse for sequence diagram event details
- * @return sequence diagram event if details are available else null
- */
- protected ITmfSyncSequenceDiagramEvent getSequenceDiagramEvent(ITmfEvent tmfEvent){
- //type = .*RECEIVE.* or .*SEND.*
- //content = sender:<sender name>:receiver:<receiver name>,signal:<signal name>
- String eventType = tmfEvent.getType().toString();
- if (eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeSend) || eventType.contains(Messages.TmfUml2SDSyncLoader_EventTypeReceive)) {
- Object sender = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSender);
- Object receiver = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldReceiver);
- Object name = tmfEvent.getContent().getField(Messages.TmfUml2SDSyncLoader_FieldSignal);
- if ((sender instanceof ITmfEventField) && (receiver instanceof ITmfEventField) && (name instanceof ITmfEventField)) {
- ITmfSyncSequenceDiagramEvent sdEvent = new TmfSyncSequenceDiagramEvent(tmfEvent,
- ((ITmfEventField) sender).getValue().toString(),
- ((ITmfEventField) receiver).getValue().toString(),
- ((ITmfEventField) name).getValue().toString());
-
- return sdEvent;
- }
- }
- return null;
- }
-</pre>
-
-The analysis looks for event type Strings containing ''SEND'' and ''RECEIVE''. If event type matches these key words, the analyzer will look for strings ''sender'', ''receiver'' and ''signal'' in the event fields of type ''ITmfEventField''. If all the data is found a sequence diagram event can be created using this information. Note that Sync Messages are assumed, which means start and end time are the same.
-
-=== How to use the Reference Implementation ===
-
-An example CTF (Common Trace Format) trace is provided that contains trace events with sequence diagram information. To download the reference trace, use the following link: [https://wiki.eclipse.org/images/3/35/ReferenceTrace.zip Reference Trace].
-
-Run an Eclipse application with TMF 3.0 or later installed. To open the Reference Sequence Diagram View, select '''Windows -> Show View -> Other... -> TMF -> Sequence Diagram''' <br>
-[[Image:images/ShowTmfSDView.png]]<br>
-
-A blank Sequence Diagram View will open.
-
-Then import the reference trace to the '''Project Explorer''' using the '''Import Trace Package...''' menu option.<br>
-[[Image:images/ImportTracePackage.png]]
-
-Next, open the trace by double-clicking on the trace element in the '''Project Explorer'''. The trace will be opened and the Sequence Diagram view will be filled.
-[[Image:images/ReferenceSeqDiagram.png]]<br>
-
-Now the reference implementation can be explored. To demonstrate the view features try the following things:
-*Select a message in the Sequence diagram. As result the corresponding event will be selected in the Events View.
-*Select an event in the Events View. As result the corresponding message in the Sequence Diagram View will be selected. If necessary, the page will be changed.
-*In the Events View, press key ''End''. As result, the Sequence Diagram view will jump to the last page.
-*In the Events View, press key ''Home''. As result, the Sequence Diagram view will jump to the first page.
-*In the Sequence Diagram View select the find button. Enter the expression '''REGISTER.*''', select '''Search for Interaction''' and press '''Find'''. As result the corresponding message will be selected in the Sequence Diagram and the corresponding event in the Events View will be selected. Select again '''Find''' the next occurrence of will be selected. Since the second occurrence is on a different page than the first, the corresponding page will be loaded.
-* In the Sequence Diagram View, select menu item '''Hide Patterns...'''. Add the filter '''BALL.*''' for '''Interaction''' only and select '''OK'''. As result all messages with name ''BALL_REQUEST'' and ''BALL_REPLY'' will be hidden. To remove the filter, select menu item '''Hide Patterns...''', deselect the corresponding filter and press '''OK'''. All the messages will be shown again.<br>
-
-=== Extending the Reference Loader ===
-
-In some case it might be necessary to change the implementation of the analysis of each ''TmfEvent'' for the generation of ''Sequence Diagram Events''. For that just extend the class ''TmfUml2SDSyncLoader'' and overwrite the method ''protected ITmfSyncSequenceDiagramEvent getSequnceDiagramEvent(TmfEvent tmfEvent)'' with your own implementation.
-
-= CTF Parser =
-
-== CTF Format ==
-CTF is a format used to store traces. It is self defining, binary and made to be easy to write to.
-Before going further, the full specification of the CTF file format can be found at http://www.efficios.com/ .
-
-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.
-
-These files can be split into two types :
-* Metadata
-* Event streams
-
-=== Metadata ===
-The metadata is either raw text or packetized text. It is tsdl encoded. it contains a description of the type of data in the event streams. It can grow over time if new events are added to a trace but it will never overwrite what is already there.
-
-=== Event Streams ===
-The event streams are a file per stream per cpu. These streams are binary and packet based. The streams store events and event information (ie lost events) The event data is stored in headers and field payloads.
-
-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"
-
-== Reading a trace ==
-In order to read a CTF trace, two steps must be done.
-* The metadata must be read to know how to read the events.
-* the events must be read.
-
-The metadata is a written in a subset of the C language called TSDL. To read it, first it is depacketized (if it is not in plain text) then the raw text is parsed by an antlr grammer. The parsing is done in two phases. There is a lexer (CTFLexer.g) which separated the metatdata text into tokens. The tokens are then pattern matched using the parser (CTFParser.g) to form an AST. This AST is walked through using "IOStructGen.java" to populate streams and traces in trace parent object.
-
-When the metadata is loaded and read, the trace object will be populated with 3 items:
-* the event definitions available per stream: a definition is a description of the datatype.
-* the event declarations available per stream: this will save declaration creation on a per event basis. They will all be created in advance, just not populated.
-* the beginning of a packet index.
-
-Now all the trace readers for the event streams have everything they need to read a trace. They will each point to one file, and read the file from packet to packet. Everytime the trace reader changes packet, the index is updated with the new packet's information. The readers are in a priority queue and sorted by timestamp. This ensures that the events are read in a sequential order. They are also sorted by file name so that in the eventuality that two events occur at the same time, they stay in the same order.
-
-== Seeking in a trace ==
-The reason for maintaining an index is to speed up seeks. In the case that a user wishes to seek to a certain timestamp, they just have to find the index entry that contains the timestamp, and go there to iterate in that packet until the proper event is found. this will reduce the searches time by an order of 8000 for a 256k paket size (kernel default).
-
-== Interfacing to TMF ==
-The trace can be read easily now but the data is still awkward to extract.
-
-=== CtfLocation ===
-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.
-
-=== CtfTmfTrace ===
-The CtfTmfTrace is a wrapper for the standard CTF trace that allows it to perform the following actions:
-* '''initTrace()''' create a trace
-* '''validateTrace()''' is the trace a CTF trace?
-* '''getLocationRatio()''' how far in the trace is my location?
-* '''seekEvent()''' sets the cursor to a certain point in a trace.
-* '''readNextEvent()''' reads the next event and then advances the cursor
-* '''getTraceProperties()''' gets the 'env' structures of the metadata
-
-=== CtfIterator ===
-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.
-
-=== CtfIteratorManager ===
-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.
-
-=== CtfTmfContext ===
-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.
-
-=== CtfTmfTimestamp ===
-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.
-
-=== CtfTmfEvent ===
-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.
-
-=== Other ===
-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.
-
-= Event matching and trace synchronization =
-
-Event matching consists in taking an event from a trace and linking it to another event in a possibly different trace. The example that comes to mind is matching network packets sent from one traced machine to another traced machine. These matches can be used to synchronize traces.
-
-Trace synchronization consists in taking traces, taken on different machines, with a different time reference, and finding the formula to transform the timestamps of some of the traces, so that they all have the same time reference.
-
-== Event matching interfaces ==
-
-Here's a description of the major parts involved in event matching. These classes are all in the ''org.eclipse.linuxtools.tmf.core.event.matching'' package:
-
-* '''ITmfEventMatching''': Controls the event matching process
-* '''ITmfMatchEventDefinition''': Describes how events are matched
-* '''IMatchProcessingUnit''': Processes the matched events
-
-== Implementation details and how to extend it ==
-
-=== ITmfEventMatching interface and derived classes ===
-
-This interface and its default abstract implementation '''TmfEventMatching''' control the event matching itself. Their only public method is ''matchEvents''. The class needs to manage how to setup the traces, and any initialization or finalization procedures.
-
-The abstract class generates an event request for each trace from which events are matched and waits for the request to complete before calling the one from another trace. The ''handleData'' method from the request calls the ''matchEvent'' method that needs to be implemented in children classes.
-
-Class '''TmfNetworkEventMatching''' is a concrete implementation of this interface. It applies to all use cases where a ''in'' event can be matched with a ''out' event (''in'' and ''out'' can be the same event, with different data). It creates a '''TmfEventDependency''' between the source and destination events. The dependency is added to the processing unit.
-
-To match events requiring other mechanisms (for instance, a series of events can be matched with another series of events), one would need to implement another class either extending '''TmfEventMatching''' or implementing '''ITmfEventMatching'''. It would most probably also require a new '''ITmfMatchEventDefinition''' implementation.
-
-=== ITmfMatchEventDefinition interface and its derived classes ===
-
-These are the classes that describe how to actually match specific events together.
-
-The '''canMatchTrace''' method will tell if a definition is compatible with a given trace.
-
-The '''getUniqueField''' method will return a list of field values that uniquely identify this event and can be used to find a previous event to match with.
-
-Typically, there would be a match definition abstract class/interface per event matching type.
-
-The interface '''ITmfNetworkMatchDefinition''' adds the ''getDirection'' method to indicate whether this event is a ''in'' or ''out'' event to be matched with one from the opposite direction.
-
-As examples, two concrete network match definitions have been implemented in the ''org.eclipse.linuxtools.lttng2.kernel.core.event.matching'' package for two compatible methods of matching TCP packets (See the LTTng User Guide on ''trace synchronization'' for information on those matching methods). Each one tells which events need to be present in the metadata of a CTF trace for this matching method to be applicable. It also returns the field values from each event that will uniquely match 2 events together.
-
-=== IMatchProcessingUnit interface and derived classes ===
-
-While matching events is an exercice in itself, it's what to do with the match that really makes this functionality interesting. This is the job of the '''IMatchProcessingUnit''' interface.
-
-'''TmfEventMatches''' provides a default implementation that only stores the matches to count them. When a new match is obtained, the ''addMatch'' is called with the match and the processing unit can do whatever needs to be done with it.
-
-A match processing unit can be an analysis in itself. For example, trace synchronization is done through such a processing unit. One just needs to set the processing unit in the TmfEventMatching constructor.
-
-== Code examples ==
-
-=== Using network packets matching in an analysis ===
-
-This example shows how one can create a processing unit inline to create a link between two events. In this example, the code already uses an event request, so there is no need here to call the ''matchEvents'' method, that will only create another request.
-
-<pre>
-class MyAnalysis extends TmfAbstractAnalysisModule {
-
- private TmfNetworkEventMatching tcpMatching;
-
- ...
-
- protected void executeAnalysis() {
-
- IMatchProcessingUnit matchProcessing = new IMatchProcessingUnit() {
- @Override
- public void matchingEnded() {
- }
-
- @Override
- public void init(ITmfTrace[] fTraces) {
- }
-
- @Override
- public int countMatches() {
- return 0;
- }
-
- @Override
- public void addMatch(TmfEventDependency match) {
- log.debug("we got a tcp match! " + match.getSourceEvent().getContent() + " " + match.getDestinationEvent().getContent());
- TmfEvent source = match.getSourceEvent();
- TmfEvent destination = match.getDestinationEvent();
- /* Create a link between the two events */
- }
- };
-
- ITmfTrace[] traces = { getTrace() };
- tcpMatching = new TmfNetworkEventMatching(traces, matchProcessing);
- tcpMatching.initMatching();
-
- MyEventRequest request = new MyEventRequest(this, i);
- getTrace().sendRequest(request);
- }
-
- public void analyzeEvent(TmfEvent event) {
- ...
- tcpMatching.matchEvent(event, 0);
- ...
- }
-
- ...
-
-}
-
-class MyEventRequest extends TmfEventRequest {
-
- private final MyAnalysis analysis;
-
- MyEventRequest(MyAnalysis analysis, int traceno) {
- super(CtfTmfEvent.class,
- TmfTimeRange.ETERNITY,
- 0,
- TmfDataRequest.ALL_DATA,
- ITmfDataRequest.ExecutionType.FOREGROUND);
- this.analysis = analysis;
- }
-
- @Override
- public void handleData(final ITmfEvent event) {
- super.handleData(event);
- if (event != null) {
- analysis.analyzeEvent(event);
- }
- }
-}
-</pre>
-
-=== Match network events from UST traces ===
-
-Suppose a client-server application is instrumented using LTTng-UST. Traces are collected on the server and some clients on different machines. The traces can be synchronized using network event matching.
-
-The following metadata describes the events:
-
-<pre>
- event {
- name = "myapp:send";
- id = 0;
- stream_id = 0;
- loglevel = 13;
- fields := struct {
- integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _sendto;
- integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _messageid;
- integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _data;
- };
- };
-
- event {
- name = "myapp:receive";
- id = 1;
- stream_id = 0;
- loglevel = 13;
- fields := struct {
- integer { size = 32; align = 8; signed = 1; encoding = none; base = 10; } _from;
- integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _messageid;
- integer { size = 64; align = 8; signed = 1; encoding = none; base = 10; } _data;
- };
- };
-</pre>
-
-One would need to write an event match definition for those 2 events as follows:
-
-<pre>
-public class MyAppUstEventMatching implements ITmfNetworkMatchDefinition {
-
- @Override
- public Direction getDirection(ITmfEvent event) {
- String evname = event.getType().getName();
- if (evname.equals("myapp:receive")) {
- return Direction.IN;
- } else if (evname.equals("myapp:send")) {
- return Direction.OUT;
- }
- return null;
- }
-
- @Override
- public List<Object> getUniqueField(ITmfEvent event) {
- List<Object> keys = new ArrayList<Object>();
-
- if (evname.equals("myapp:receive")) {
- keys.add(event.getContent().getField("from").getValue());
- keys.add(event.getContent().getField("messageid").getValue());
- } else {
- keys.add(event.getContent().getField("sendto").getValue());
- keys.add(event.getContent().getField("messageid").getValue());
- }
-
- return keys;
- }
-
- @Override
- public boolean canMatchTrace(ITmfTrace trace) {
- if (!(trace instanceof CtfTmfTrace)) {
- return false;
- }
- CtfTmfTrace ktrace = (CtfTmfTrace) trace;
- String[] events = { "myapp:receive", "myapp:send" };
- return ktrace.hasAtLeastOneOfEvents(events);
- }
-
- @Override
- public MatchingType[] getApplicableMatchingTypes() {
- MatchingType[] types = { MatchingType.NETWORK };
- return types;
- }
-
-}
-</pre>
-
-Somewhere in code that will be executed at the start of the plugin (like in the Activator), the following code will have to be run:
-
-<pre>
-TmfEventMatching.registerMatchObject(new MyAppUstEventMatching());
-</pre>
-
-Now, only adding the traces in an experiment and clicking the '''Synchronize traces''' menu element would synchronize the traces using the new definition for event matching.
-
-== Trace synchronization ==
-
-Trace synchronization classes and interfaces are located in the ''org.eclipse.linuxtools.tmf.core.synchronization'' package.
-
-=== Synchronization algorithm ===
-
-Synchronization algorithms are used to synchronize traces from events matched between traces. After synchronization, traces taken on different machines with different time references see their timestamps modified such that they all use the same time reference (typically, the time of at least one of the traces). With traces from different machines, it is impossible to have perfect synchronization, so the result is a best approximation that takes network latency into account.
-
-The abstract class '''SynchronizationAlgorithm''' is a processing unit for matches. New synchronization algorithms must extend this one, it already contains the functions to get the timestamp transforms for different traces.
-
-The ''fully incremental convex hull'' synchronization algorithm is the default synchronization algorithm.
-
-While the synchronization system provisions for more synchronization algorithms, there is not yet a way to select one, the experiment's trace synchronization uses the default algorithm. To test a new synchronization algorithm, the synchronization should be called directly like this:
-
-<pre>
-SynchronizationAlgorithm syncAlgo = new MyNewSynchronizationAlgorithm();
-syncAlgo = SynchronizationManager.synchronizeTraces(syncFile, traces, syncAlgo, true);
-</pre>
-
-=== Timestamp transforms ===
-
-Timestamp transforms are the formulae used to transform the timestamps from a trace into the reference time. The '''ITmfTimestampTransform''' is the interface to implement to add a new transform.
-
-The following classes implement this interface:
-
-* '''TmfTimestampTransform''': default transform. It cannot be instantiated, it has a single static object TmfTimestampTransform.IDENTITY, which returns the original timestamp.
-* '''TmfTimestampTransformLinear''': transforms the timestamp using a linear formula: ''f(t) = at + b'', where ''a'' and ''b'' are computed by the synchronization algorithm.
-
-One could extend the interface for other timestamp transforms, for instance to have a transform where the formula would change over the course of the trace.
-
-== Todo ==
-
-Here's a list of features not yet implemented that would enhance trace synchronization and event matching:
-
-* Ability to select a synchronization algorithm
-* Implement a better way to select the reference trace instead of arbitrarily taking the first in alphabetical order (for instance, the minimum spanning tree algorithm by Masoume Jabbarifar (article on the subject not published yet))
-* Ability to join traces from the same host so that even if one of the traces is not synchronized with the reference trace, it will take the same timestamp transform as the one on the same machine.
-* Instead of having the timestamp transforms per trace, have the timestamp transform as part of an experiment context, so that the trace's specific analysis, like the state system, are in the original trace, but are transformed only when needed for an experiment analysis.
-* Add more views to display the synchronization information (only textual statistics are available for now)
-
-= Analysis Framework =
-
-Analysis modules are useful to tell the user exactly what can be done with a trace. The analysis framework provides an easy way to access and execute the modules and open the various outputs available.
-
-Analyses can have parameters they can use in their code. They also have outputs registered to them to display the results from their execution.
-
-== Creating a new module ==
-
-All analysis modules must implement the '''IAnalysisModule''' interface from the o.e.l.tmf.core project. An abstract class, '''TmfAbstractAnalysisModule''', provides a good base implementation. It is strongly suggested to use it as a superclass of any new analysis.
-
-=== Example ===
-
-This example shows how to add a simple analysis module for an LTTng kernel trace with two parameters.
-
-<pre>
-public class MyLttngKernelAnalysis extends TmfAbstractAnalysisModule {
-
- public static final String PARAM1 = "myparam";
- public static final String PARAM2 = "myotherparam";
-
- @Override
- public boolean canExecute(ITmfTrace trace) {
- /* This just makes sure the trace is an Lttng kernel trace, though
- usually that should have been done by specifying the trace type
- this analysis module applies to */
- if (!LttngKernelTrace.class.isAssignableFrom(trace.getClass())) {
- return false;
- }
-
- /* Does the trace contain the appropriate events? */
- String[] events = { "sched_switch", "sched_wakeup" };
- return ((LttngKernelTrace) trace).hasAllEvents(events);
- }
-
- @Override
- protected void canceling() {
- /* The job I am running in is being cancelled, let's clean up */
- }
-
- @Override
- protected boolean executeAnalysis(final IProgressMonitor monitor) {
- /*
- * I am running in an Eclipse job, and I already know I can execute
- * on a given trace.
- *
- * In the end, I will return true if I was successfully completed or
- * false if I was either interrupted or something wrong occurred.
- */
- Object param1 = getParameter(PARAM1);
- int param2 = (Integer) getParameter(PARAM2);
- }
-
- @Override
- public Object getParameter(String name) {
- Object value = super.getParameter(name);
- /* Make sure the value of param2 is of the right type. For sake of
- simplicity, the full parameter format validation is not presented
- here */
- if ((value != null) && name.equals(PARAM2) && (value instanceof String)) {
- return Integer.parseInt((String) value);
- }
- return value;
- }
-
-}
-</pre>
-
-=== Available base analysis classes and interfaces ===
-
-The following are available as base classes for analysis modules. They also extend the abstract '''TmfAbstractAnalysisModule'''
-
-* '''TmfStateSystemAnalysisModule''': A base analysis module that builds one state system. A module extending this class only needs to provide a state provider and the type of state system backend to use. All state systems should now use this base class as it also contains all the methods to actually create the state sytem with a given backend.
-
-The following interfaces can optionally be implemented by analysis modules if they use their functionalities. For instance, some utility views, like the State System Explorer, may have access to the module's data through these interfaces.
-
-* '''ITmfAnalysisModuleWithStateSystems''': Modules implementing this have one or more state systems included in them. For example, a module may "hide" 2 state system modules for its internal workings. By implementing this interface, it tells that it has state systems and can return them if required.
-
-=== How it works ===
-
-Analyses are managed through the '''TmfAnalysisManager'''. The analysis manager is a singleton in the application and keeps track of all available analysis modules, with the help of '''IAnalysisModuleHelper'''. It can be queried to get the available analysis modules, either all of them or only those for a given tracetype. The helpers contain the non-trace specific information on an analysis module: its id, its name, the tracetypes it applies to, etc.
-
-When a trace is opened, the helpers for the applicable analysis create new instances of the analysis modules. The analysis are then kept in a field of the trace and can be executed automatically or on demand.
-
-The analysis is executed by calling the '''IAnalysisModule#schedule()''' method. This method makes sure the analysis is executed only once and, if it is already running, it won't start again. The analysis itself is run inside an Eclipse job that can be cancelled by the user or the application. The developer must consider the progress monitor that comes as a parameter of the '''executeAnalysis()''' method, to handle the proper cancellation of the processing. The '''IAnalysisModule#waitForCompletion()''' method will block the calling thread until the analysis is completed. The method will return whether the analysis was successfully completed or if it was cancelled.
-
-A running analysis can be cancelled by calling the '''IAnalysisModule#cancel()''' method. This will set the analysis as done, so it cannot start again unless it is explicitly reset. This is done by calling the protected method '''resetAnalysis'''.
-
-== Telling TMF about the analysis module ==
-
-Now that the analysis module class exists, it is time to hook it to the rest of TMF so that it appears under the traces in the project explorer. The way to do so is to add an extension of type ''org.eclipse.linuxtools.tmf.core.analysis'' to a plugin, either through the ''Extensions'' tab of the Plug-in Manifest Editor or by editing directly the plugin.xml file.
-
-The following code shows what the resulting plugin.xml file should look like.
-
-<pre>
-<extension
- point="org.eclipse.linuxtools.tmf.core.analysis">
- <module
- id="my.lttng.kernel.analysis.id"
- name="My LTTng Kernel Analysis"
- analysis_module="my.plugin.package.MyLttngKernelAnalysis"
- automatic="true">
- <parameter
- name="myparam">
- </parameter>
- <parameter
- default_value="3"
- name="myotherparam">
- <tracetype
- class="org.eclipse.linuxtools.lttng2.kernel.core.trace.LttngKernelTrace">
- </tracetype>
- </module>
-</extension>
-</pre>
-
-This defines an analysis module where the ''analysis_module'' attribute corresponds to the module class and must implement IAnalysisModule. This module has 2 parameters: ''myparam'' and ''myotherparam'' which has default value of 3. The ''tracetype'' element tells which tracetypes this analysis applies to. There can be many tracetypes. Also, the ''automatic'' attribute of the module indicates whether this analysis should be run when the trace is opened, or wait for the user's explicit request.
-
-Note that with these extension points, it is possible to use the same module class for more than one analysis (with different ids and names). That is a desirable behavior. For instance, a third party plugin may add a new tracetype different from the one the module is meant for, but on which the analysis can run. Also, different analyses could provide different results with the same module class but with different default values of parameters.
-
-== Attaching outputs and views to the analysis module ==
-
-Analyses will typically produce outputs the user can examine. Outputs can be a text dump, a .dot file, an XML file, a view, etc. All output types must implement the '''IAnalysisOutput''' interface.
-
-An output can be registered to an analysis module at any moment by calling the '''IAnalysisModule#registerOutput()''' method. Analyses themselves may know what outputs are available and may register them in the analysis constructor or after analysis completion.
-
-The various concrete output types are:
-
-* '''TmfAnalysisViewOutput''': It takes a view ID as parameter and, when selected, opens the view.
-
-=== Using the extension point to add outputs ===
-
-Analysis outputs can also be hooked to an analysis using the same extension point ''org.eclipse.linuxtools.tmf.core.analysis'' in the plugin.xml file. Outputs can be matched either to a specific analysis identified by an ID, or to all analysis modules extending or implementing a given class or interface.
-
-The following code shows how to add a view output to the analysis defined above directly in the plugin.xml file. This extension does not have to be in the same plugin as the extension defining the analysis. Typically, an analysis module can be defined in a core plugin, along with some outputs that do not require UI elements. Other outputs, like views, who need UI elements, will be defined in a ui plugin.
-
-<pre>
-<extension
- point="org.eclipse.linuxtools.tmf.core.analysis">
- <output
- class="org.eclipse.linuxtools.tmf.ui.analysis.TmfAnalysisViewOutput"
- id="my.plugin.package.ui.views.myView">
- <analysisId
- id="my.lttng.kernel.analysis.id">
- </analysisId>
- </output>
- <output
- class="org.eclipse.linuxtools.tmf.ui.analysis.TmfAnalysisViewOutput"
- id="my.plugin.package.ui.views.myMoreGenericView">
- <analysisModuleClass
- class="my.plugin.package.core.MyAnalysisModuleClass">
- </analysisModuleClass>
- </output>
-</extension>
-</pre>
-
-== Providing help for the module ==
-
-For now, the only way to provide a meaningful help message to the user is by overriding the '''IAnalysisModule#getHelpText()''' method and return a string that will be displayed in a message box.
-
-What still needs to be implemented is for a way to add a full user/developer documentation with mediawiki text file for each module and automatically add it to Eclipse Help. Clicking on the Help menu item of an analysis module would open the corresponding page in the help.
-
-== Using analysis parameter providers ==
-
-An analysis may have parameters that can be used during its execution. Default values can be set when describing the analysis module in the plugin.xml file, or they can use the '''IAnalysisParameterProvider''' interface to provide values for parameters. '''TmfAbstractAnalysisParamProvider''' provides an abstract implementation of this interface, that automatically notifies the module of a parameter change.
-
-=== Example parameter provider ===
-
-The following example shows how to have a parameter provider listen to a selection in the LTTng kernel Control Flow view and send the thread id to the analysis.
-
-<pre>
-public class MyLttngKernelParameterProvider extends TmfAbstractAnalysisParamProvider {
-
- private ControlFlowEntry fCurrentEntry = null;
-
- private static final String NAME = "My Lttng kernel parameter provider"; //$NON-NLS-1$
-
- private ISelectionListener selListener = new ISelectionListener() {
- @Override
- public void selectionChanged(IWorkbenchPart part, ISelection selection) {
- if (selection instanceof IStructuredSelection) {
- Object element = ((IStructuredSelection) selection).getFirstElement();
- if (element instanceof ControlFlowEntry) {
- ControlFlowEntry entry = (ControlFlowEntry) element;
- setCurrentThreadEntry(entry);
- }
- }
- }
- };
-
- /*
- * Constructor
- */
- public CriticalPathParameterProvider() {
- super();
- registerListener();
- }
-
- @Override
- public String getName() {
- return NAME;
- }
-
- @Override
- public Object getParameter(String name) {
- if (fCurrentEntry == null) {
- return null;
- }
- if (name.equals(MyLttngKernelAnalysis.PARAM1)) {
- return fCurrentEntry.getThreadId()
- }
- return null;
- }
-
- @Override
- public boolean appliesToTrace(ITmfTrace trace) {
- return (trace instanceof LttngKernelTrace);
- }
-
- private void setCurrentThreadEntry(ControlFlowEntry entry) {
- if (!entry.equals(fCurrentEntry)) {
- fCurrentEntry = entry;
- this.notifyParameterChanged(MyLttngKernelAnalysis.PARAM1);
- }
- }
-
- private void registerListener() {
- final IWorkbench wb = PlatformUI.getWorkbench();
-
- final IWorkbenchPage activePage = wb.getActiveWorkbenchWindow().getActivePage();
-
- /* Add the listener to the control flow view */
- view = activePage.findView(ControlFlowView.ID);
- if (view != null) {
- view.getSite().getWorkbenchWindow().getSelectionService().addPostSelectionListener(selListener);
- view.getSite().getWorkbenchWindow().getPartService().addPartListener(partListener);
- }
- }
-
-}
-</pre>
-
-=== Register the parameter provider to the analysis ===
-
-To have the parameter provider class register to analysis modules, it must first register through the analysis manager. It can be done in a plugin's activator as follows:
-
-<pre>
-@Override
-public void start(BundleContext context) throws Exception {
- /* ... */
- TmfAnalysisManager.registerParameterProvider("my.lttng.kernel.analysis.id", MyLttngKernelParameterProvider.class)
-}
-</pre>
-
-where '''MyLttngKernelParameterProvider''' will be registered to analysis ''"my.lttng.kernel.analysis.id"''. When the analysis module is created, the new module will register automatically to the singleton parameter provider instance. Only one module is registered to a parameter provider at a given time, the one corresponding to the currently selected trace.
-
-== Providing requirements to analyses ==
-
-=== 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).
-
-=== 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()'''.
-
-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.
-
-<pre>
-@Override
-public Iterable<TmfAnalysisRequirement> getAnalysisRequirements() {
- Set<TmfAnalysisRequirement> requirements = new HashSet<>();
-
- /* Create requirements of type 'event' and 'domain' */
- TmfAnalysisRequirement eventRequirement = new TmfAnalysisRequirement("event");
- TmfAnalysisRequirement domainRequirement = new TmfAnalysisRequirement("domain");
-
- /* Add the values */
- domainRequirement.addValue("kernel", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
- eventRequirement.addValue("sched_switch", TmfAnalysisRequirement.ValuePriorityLevel.MANDATORY);
- eventRequirement.addValue("sched_wakeup", TmfAnalysisRequirement.ValuePriorityLevel.OPTIONAL);
-
- /* An information about the events */
- eventRequirement.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);
-
- return requirements;
-}
-</pre>
-
-
-== TODO ==
-
-Here's a list of features not yet implemented that would improve the analysis module user experience:
-
-* Implement help using the Eclipse Help facility (without forgetting an eventual command line request)
-* The abstract class '''TmfAbstractAnalysisModule''' executes an analysis as a job, but nothing compels a developer to do so for an analysis implementing the '''IAnalysisModule''' interface. We should force the execution of the analysis as a job, either from the trace itself or using the TmfAnalysisManager or by some other mean.
-* Views and outputs are often registered by the analysis themselves (forcing them often to be in the .ui packages because of the views), because there is no other easy way to do so. We should extend the analysis extension point so that .ui plugins or other third-party plugins can add outputs to a given analysis that resides in the core.
-* Improve the user experience with the analysis:
-** Allow the user to select which analyses should be available, per trace or per project.
-** Allow the user to view all available analyses even though he has no imported traces.
-** Allow the user to generate traces for a given analysis, or generate a template to generate the trace that can be sent as parameter to the tracer.
-** Give the user a visual status of the analysis: not executed, in progress, completed, error.
-** Give a small screenshot of the output as icon for it.
-** Allow to specify parameter values from the GUI.
-* Add the possibility for an analysis requirement to be composed of another requirement.
-* Generate a trace session from analysis requirements.
-
-
-= Performance Tests =
-
-Performance testing allows to calculate some metrics (CPU time, Memory Usage, etc) that some part of the code takes during its execution. These metrics can then be used as is for information on the system's execution, or they can be compared either with other execution scenarios, or previous runs of the same scenario, for instance, after some optimization has been done on the code.
-
-For automatic performance metric computation, we use the ''org.eclipse.test.performance'' plugin, provided by the Eclipse Test Feature.
-
-== Add performance tests ==
-
-=== Where ===
-
-Performance tests are unit tests and they are added to the corresponding unit tests plugin. To separate performance tests from unit tests, a separate source folder, typically named ''perf'', is added to the plug-in.
-
-Tests are to be added to a package under the ''perf'' directory, the package name would typically match the name of the package it is testing. For each package, a class named '''AllPerfTests''' would list all the performance tests classes inside this package. And like for unit tests, a class named '''AllPerfTests''' for the plug-in would list all the packages' '''AllPerfTests''' classes.
-
-When adding performance tests for the first time in a plug-in, the plug-in's '''AllPerfTests''' class should be added to the global list of performance tests, found in package ''org.eclipse.linuxtools.lttng.alltests'', in class '''RunAllPerfTests'''. This will ensure that performance tests for the plug-in are run along with the other performance tests
-
-=== How ===
-
-TMF is using the org.eclipse.test.performance framework for performance tests. Using this, performance metrics are automatically taken and, if many runs of the tests are run, average and standard deviation are automatically computed. Results can optionally be stored to a database for later use.
-
-Here is an example of how to use the test framework in a performance test:
-
-<pre>
-public class AnalysisBenchmark {
-
- private static final String TEST_ID = "org.eclipse.linuxtools#LTTng kernel analysis";
- private static final CtfTmfTestTrace testTrace = CtfTmfTestTrace.TRACE2;
- private static final int LOOP_COUNT = 10;
-
- /**
- * Performance test
- */
- @Test
- public void testTrace() {
- assumeTrue(testTrace.exists());
-
- /** Create a new performance meter for this scenario */
- Performance perf = Performance.getDefault();
- PerformanceMeter pm = perf.createPerformanceMeter(TEST_ID);
-
- /** Optionally, tag this test for summary or global summary on a given dimension */
- perf.tagAsSummary(pm, "LTTng Kernel Analysis", Dimension.CPU_TIME);
- perf.tagAsGlobalSummary(pm, "LTTng Kernel Analysis", Dimension.CPU_TIME);
-
- /** The test will be run LOOP_COUNT times */
- for (int i = 0; i < LOOP_COUNT; i++) {
-
- /** Start each run of the test with new objects to avoid different code paths */
- try (IAnalysisModule module = new LttngKernelAnalysisModule();
- LttngKernelTrace trace = new LttngKernelTrace()) {
- module.setId("test");
- trace.initTrace(null, testTrace.getPath(), CtfTmfEvent.class);
- module.setTrace(trace);
-
- /** The analysis execution is being tested, so performance metrics
- * are taken before and after the execution */
- pm.start();
- TmfTestHelper.executeAnalysis(module);
- pm.stop();
-
- /*
- * Delete the supplementary files, so next iteration rebuilds
- * the state system.
- */
- File suppDir = new File(TmfTraceManager.getSupplementaryFileDir(trace));
- for (File file : suppDir.listFiles()) {
- file.delete();
- }
-
- } catch (TmfAnalysisException | TmfTraceException e) {
- fail(e.getMessage());
- }
- }
-
- /** Once the test has been run many times, committing the results will
- * calculate average, standard deviation, and, if configured, save the
- * data to a database */
- pm.commit();
- }
-}
-
-</pre>
-
-For more information, see [http://wiki.eclipse.org/Performance/Automated_Tests The Eclipse Performance Test How-to]
-
-Some rules to help write performance tests are explained in section [[#ABC of performance testing | ABC of performance testing]].
-
-=== Run a performance test ===
-
-Performance tests are unit tests, so, just like unit tests, they can be run by right-clicking on a performance test class and selecting ''Run As'' -> ''Junit Plug-in Test''.
-
-By default, if no database has been configured, results will be displayed in the Console at the end of the test.
-
-Here is the sample output from the test described in the previous section. It shows all the metrics that have been calculated during the test.
-
-<pre>
-Scenario 'org.eclipse.linuxtools#LTTng kernel analysis' (average over 10 samples):
- System Time: 3.04s (95% in [2.77s, 3.3s]) Measurable effect: 464ms (1.3 SDs) (required sample size for an effect of 5% of mean: 94)
- Used Java Heap: -1.43M (95% in [-33.67M, 30.81M]) Measurable effect: 57.01M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6401)
- Working Set: 14.43M (95% in [-966.01K, 29.81M]) Measurable effect: 27.19M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6400)
- Elapsed Process: 3.04s (95% in [2.77s, 3.3s]) Measurable effect: 464ms (1.3 SDs) (required sample size for an effect of 5% of mean: 94)
- Kernel time: 621ms (95% in [586ms, 655ms]) Measurable effect: 60ms (1.3 SDs) (required sample size for an effect of 5% of mean: 39)
- CPU Time: 6.06s (95% in [5.02s, 7.09s]) Measurable effect: 1.83s (1.3 SDs) (required sample size for an effect of 5% of mean: 365)
- Hard Page Faults: 0 (95% in [0, 0]) Measurable effect: 0 (1.3 SDs) (required sample size for an effect of 5% of stdev: 6400)
- Soft Page Faults: 9.27K (95% in [3.28K, 15.27K]) Measurable effect: 10.6K (1.3 SDs) (required sample size for an effect of 5% of mean: 5224)
- Text Size: 0 (95% in [0, 0])
- Data Size: 0 (95% in [0, 0])
- Library Size: 32.5M (95% in [-12.69M, 77.69M]) Measurable effect: 79.91M (1.3 SDs) (required sample size for an effect of 5% of stdev: 6401)
-</pre>
-
-Results from performance tests can be saved automatically to a derby database. Derby can be run either in embedded mode, locally on a machine, or on a server. More information on setting up derby for performance tests can be found here: [http://wiki.eclipse.org/Performance/Automated_Tests The Eclipse Performance Test How-to]. The following documentation will show how to configure an Eclipse run configuration to store results on a derby database located on a server.
-
-Note that to store results in a derby database, the ''org.apache.derby'' plug-in must be available within your Eclipse. Since it is an optional dependency, it is not included in the target definition. It can be installed via the '''Orbit''' repository, in ''Help'' -> ''Install new software...''. If the '''Orbit''' repository is not listed, click on the latest one from [http://download.eclipse.org/tools/orbit/downloads/] and copy the link under ''Orbit Build Repository''.
-
-To store the data to a database, it needs to be configured in the run configuration. In ''Run'' -> ''Run configurations..'', under ''Junit Plug-in Test'', find the run configuration that corresponds to the test you wish to run, or create one if it is not present yet.
-
-In the ''Arguments'' tab, in the box under ''VM Arguments'', add on separate lines the following information
-
-<pre>
--Declipse.perf.dbloc=//javaderby.dorsal.polymtl.ca
--Declipse.perf.config=build=mybuild;host=myhost;config=linux;jvm=1.7
-</pre>
-
-The ''eclipse.perf.dbloc'' parameter is the url (or filename) of the derby database. The database is by default named ''perfDB'', with username and password ''guest''/''guest''. If the database does not exist, it will be created, initialized and populated.
-
-The ''eclipse.perf.config'' parameter identifies a '''variation''': It typically identifies the build on which is it run (commitId and/or build date, etc), the machine (host) on which it is run, the configuration of the system (for example Linux or Windows), the jvm etc. That parameter is a list of ';' separated key-value pairs. To be backward-compatible with the Eclipse Performance Tests Framework, the 4 keys mentioned above are mandatory, but any key-value pairs can be used.
-
-== ABC of performance testing ==
-
-Here follow some rules to help design good and meaningful performance tests.
-
-=== Determine what to test ===
-
-For tests to be significant, it is important to choose what exactly is to be tested and make sure it is reproducible every run. To limit the amount of noise caused by the TMF framework, the performance test code should be tweaked so that only the method under test is run. For instance, a trace should not be "opened" (by calling the ''traceOpened()'' method) to test an analysis, since the ''traceOpened'' method will also trigger the indexing and the execution of all applicable automatic analysis.
-
-For each code path to test, multiple scenarios can be defined. For instance, an analysis could be run on different traces, with different sizes. The results will show how the system scales and/or varies depending on the objects it is executed on.
-
-The number of '''samples''' used to compute the results is also important. The code to test will typically be inside a '''for''' loop that runs exactly the same code each time for a given number of times. All objects used for the test must start in the same state at each iteration of the loop. For instance, any trace used during an execution should be disposed of at the end of the loop, and any supplementary file that may have been generated in the run should be deleted.
-
-Before submitting a performance test to the code review, you should run it a few times (with results in the Console) and see if the standard deviation is not too large and if the results are reproducible.
-
-=== Metrics descriptions and considerations ===
-
-CPU time: CPU time represent the total time spent on CPU by the current process, for the time of the test execution. It is the sum of the time spent by all threads. On one hand, it is more significant than the elapsed time, since it should be the same no matter how many CPU cores the computer has. But since it calculates the time of every thread, one has to make sure that only threads related to what is being tested are executed during that time, or else the results will include the times of those other threads. For an application like TMF, it is hard to control all the threads, and empirically, it is found to vary a lot more than the system time from one run to the other.
-
-System time (Elapsed time): The time between the start and the end of the execution. It will vary depending on the parallelisation of the threads and the load of the machine.
-
-Kernel time: Time spent in kernel mode
-
-Used Java Heap: It is the difference between the memory used at the beginning of the execution and at the end. This metric may be useful to calculate the overall size occupied by the data generated by the test run, by forcing a garbage collection before taking the metrics at the beginning and at the end of the execution. But it will not show the memory used throughout the execution. There can be a large standard deviation. The reason for this is that when benchmarking methods that trigger tasks in different threads, like signals and/or analysis, these other threads might be in various states at each run of the test, which will impact the memory usage calculated. When using this metric, either make sure the method to test does not trigger external threads or make sure you wait for them to finish.
-
-= Network Tracing =
-
-== Adding a protocol ==
-
-Supporting a new network protocol in TMF is straightforward. Minimal effort is required to support new protocols. In this tutorial, the UDP protocol will be added to the list of supported protocols.
-
-=== Architecture ===
-
-All the TMF pcap-related code is divided in three projects (not considering the tests plugins):
-* '''org.eclipse.linuxtools.pcap.core''', which contains the parser that will read pcap files and constructs the different packets from a ByteBuffer. It also contains means to build packet streams, which are conversation (list of packets) between two endpoints. To add a protocol, almost all of the work will be in that project.
-* '''org.eclipse.linuxtools.tmf.pcap.core''', which contains TMF-specific concepts and act as a wrapper between TMF and the pcap parsing library. It only depends on org.eclipse.linuxtools.tmf.core and org.eclipse.pcap.core. To add a protocol, one file must be edited in this project.
-* '''org.eclipse.linuxtools.tmf.pcap.ui''', which contains all TMF pcap UI-specific concepts, such as the views and perspectives. No work is needed in that project.
-
-=== UDP Packet Structure ===
-
-The UDP is a transport-layer protocol that does not guarantee message delivery nor in-order message reception. A UDP packet (datagram) has the following [http://en.wikipedia.org/wiki/User_Datagram_Protocol#Packet_structure structure]:
-
-{| class="wikitable" style="margin: 0 auto; text-align: center;"
-|-
-! style="border-bottom:none; border-right:none;"| ''Offsets''
-! style="border-left:none;"| Octet
-! colspan="8" | 0
-! colspan="8" | 1
-! colspan="8" | 2
-! colspan="8" | 3
-|-
-! style="border-top: none" | Octet
-! <tt>Bit</tt>!!<tt> 0</tt>!!<tt> 1</tt>!!<tt> 2</tt>!!<tt> 3</tt>!!<tt> 4</tt>!!<tt> 5</tt>!!<tt> 6</tt>!!<tt> 7</tt>!!<tt> 8</tt>!!<tt> 9</tt>!!<tt>10</tt>!!<tt>11</tt>!!<tt>12</tt>!!<tt>13</tt>!!<tt>14</tt>!!<tt>15</tt>!!<tt>16</tt>!!<tt>17</tt>!!<tt>18</tt>!!<tt>19</tt>!!<tt>20</tt>!!<tt>21</tt>!!<tt>22</tt>!!<tt>23</tt>!!<tt>24</tt>!!<tt>25</tt>!!<tt>26</tt>!!<tt>27</tt>!!<tt>28</tt>!!<tt>29</tt>!!<tt>30</tt>!!<tt>31</tt>
-|-
-! 0
-!<tt> 0</tt>
-| colspan="16" style="background:#fdd;"| Source port || colspan="16"| Destination port
-|-
-! 4
-!<tt>32</tt>
-| colspan="16"| Length || colspan="16" style="background:#fdd;"| Checksum
-|}
-
-Knowing that, we can define an UDPPacket class that contains those fields.
-
-=== Creating the UDPPacket ===
-
-First, in org.eclipse.linuxtools.pcap.core, create a new package named '''org.eclipse.linuxtools.pcap.core.protocol.name''' with name being the name of the new protocol. In our case name is udp so we create the package '''org.eclipse.linuxtools.pcap.core.protocol.udp'''. All our work is going in this package.
-
-In this package, we create a new class named UDPPacket that extends Packet. All new protocol must define a packet type that extends the abstract class Packet. We also add different fields:
-* ''Packet'' '''fChildPacket''', which is the packet encapsulated by this UDP packet, if it exists. This field will be initialized by findChildPacket().
-* ''ByteBuffer'' '''fPayload''', which is the payload of this packet. Basically, it is the UDP packet without its header.
-* ''int'' '''fSourcePort''', which is an unsigned 16-bits field, that contains the source port of the packet (see packet structure).
-* ''int'' '''fDestinationPort''', which is an unsigned 16-bits field, that contains the destination port of the packet (see packet structure).
-* ''int'' '''fTotalLength''', which is an unsigned 16-bits field, that contains the total length (header + payload) of the packet.
-* ''int'' '''fChecksum''', which is an unsigned 16-bits field, that contains a checksum to verify the integrity of the data.
-* ''UDPEndpoint'' '''fSourceEndpoint''', which contains the source endpoint of the UDPPacket. The UDPEndpoint class will be created later in this tutorial.
-* ''UDPEndpoint'' '''fDestinationEndpoint''', which contains the destination endpoint of the UDPPacket.
-* ''ImmutableMap<String, String>'' '''fFields''', which is a map that contains all the packet fields (see in data structure) which assign a field name with its value. Those values will be displayed on the UI.
-
-We also create the UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) constructor. The parameters are:
-* ''PcapFile'' '''file''', which is the pcap file to which this packet belongs.
-* ''Packet'' '''parent''', which is the packet encasulating this UDPPacket
-* ''ByteBuffer'' '''packet''', which is a ByteBuffer that contains all the data necessary to initialize the fields of this UDPPacket. We will retrieve bytes from it during object construction.
-
-The following class is obtained:
-
-<pre>
-package org.eclipse.linuxtools.pcap.core.protocol.udp;
-
-import java.nio.ByteBuffer;
-import java.util.Map;
-
-import org.eclipse.linuxtools.internal.pcap.core.endpoint.ProtocolEndpoint;
-import org.eclipse.linuxtools.internal.pcap.core.packet.BadPacketException;
-import org.eclipse.linuxtools.internal.pcap.core.packet.Packet;
-
-public class UDPPacket extends Packet {
-
- private final @Nullable Packet fChildPacket;
- private final @Nullable ByteBuffer fPayload;
-
- private final int fSourcePort;
- private final int fDestinationPort;
- private final int fTotalLength;
- private final int fChecksum;
-
- private @Nullable UDPEndpoint fSourceEndpoint;
- private @Nullable UDPEndpoint fDestinationEndpoint;
-
- private @Nullable ImmutableMap<String, String> fFields;
-
- /**
- * Constructor of the UDP Packet class.
- *
- * @param file
- * The file that contains this packet.
- * @param parent
- * The parent packet of this packet (the encapsulating packet).
- * @param packet
- * The entire packet (header and payload).
- * @throws BadPacketException
- * Thrown when the packet is erroneous.
- */
- public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
- super(file, parent, Protocol.UDP);
- // TODO Auto-generated constructor stub
- }
-
-
- @Override
- public Packet getChildPacket() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public ByteBuffer getPayload() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public boolean validate() {
- // TODO Auto-generated method stub
- return false;
- }
-
- @Override
- protected Packet findChildPacket() throws BadPacketException {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public ProtocolEndpoint getSourceEndpoint() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public ProtocolEndpoint getDestinationEndpoint() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public Map<String, String> getFields() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public String getLocalSummaryString() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- protected String getSignificationString() {
- // TODO Auto-generated method stub
- return null;
- }
-
- @Override
- public boolean equals(Object obj) {
- // TODO Auto-generated method stub
- return false;
- }
-
- @Override
- public int hashCode() {
- // TODO Auto-generated method stub
- return 0;
- }
-
-}
-</pre>
-
-Now, we implement the constructor. It is done in four steps:
-* We initialize fSourceEndpoint, fDestinationEndpoint and fFields to null, since those are lazy-loaded. This allows faster construction of the packet and thus faster parsing.
-* We initialize fSourcePort, fDestinationPort, fTotalLength, fChecksum using ByteBuffer packet. Thanks to the packet data structure, we can simply retrieve packet.getShort() to get the value. Since there is no unsigned in Java, special care is taken to avoid negative number. We use the utility method ConversionHelper.unsignedShortToInt() to convert it to an integer, and initialize the fields.
-* Now that the header is parsed, we take the rest of the ByteBuffer packet to initialize the payload, if there is one. To do this, we simply generate a new ByteBuffer starting from the current position.
-* We initialize the field fChildPacket using the method findChildPacket()
-
-The following constructor is obtained:
-<pre>
- public UDPPacket(PcapFile file, @Nullable Packet parent, ByteBuffer packet) throws BadPacketException {
- super(file, parent, Protocol.UDP);
-
- // The endpoints and fFields are lazy loaded. They are defined in the get*Endpoint()
- // methods.
- fSourceEndpoint = null;
- fDestinationEndpoint = null;
- fFields = null;
-
- // Initialize the fields from the ByteBuffer
- packet.order(ByteOrder.BIG_ENDIAN);
- packet.position(0);
-
- fSourcePort = ConversionHelper.unsignedShortToInt(packet.getShort());
- fDestinationPort = ConversionHelper.unsignedShortToInt(packet.getShort());
- fTotalLength = ConversionHelper.unsignedShortToInt(packet.getShort());
- fChecksum = ConversionHelper.unsignedShortToInt(packet.getShort());
-
- // Initialize the payload
- if (packet.array().length - packet.position() > 0) {
- byte[] array = new byte[packet.array().length - packet.position()];
- packet.get(array);
-
- ByteBuffer payload = ByteBuffer.wrap(array);
- payload.order(ByteOrder.BIG_ENDIAN);
- payload.position(0);
- fPayload = payload;
- } else {
- fPayload = null;
- }
-
- // Find child
- fChildPacket = findChildPacket();
-
- }
-</pre>
-
-Then, we implement the following methods:
-* ''public Packet'' '''getChildPacket()''': simple getter of fChildPacket
-* ''public ByteBuffer'' '''getPayload()''': simple getter of fPayload
-* ''public boolean'' '''validate()''': method that checks if the packet is valid. In our case, the packet is valid if the retrieved checksum fChecksum and the real checksum (that we can compute using the fields and payload of UDPPacket) are the same.
-* ''protected Packet'' '''findChildPacket()''': method that create a new packet if a encapsulated protocol is found. For instance, based on the fDestinationPort, it could determine what the encapsulated protocol is and creates a new packet object.
-* ''public ProtocolEndpoint'' '''getSourceEndpoint()''': method that initializes and returns the source endpoint.
-* ''public ProtocolEndpoint'' '''getDestinationEndpoint()''': method that initializes and returns the destination endpoint.
-* ''public Map<String, String>'' '''getFields()''': method that initializes and returns the map containing the fields matched to their value.
-* ''public String'' '''getLocalSummaryString()''': method that returns a string summarizing the most important fields of the packet. There is no need to list all the fields, just the most important one. This will be displayed on UI.
-* ''protected String'' '''getSignificationString()''': method that returns a string describing the meaning of the packet. If there is no particular meaning, it is possible to return getLocalSummaryString().
-* public boolean'' '''equals(Object obj)''': Object's equals method.
-* public int'' '''hashCode()''': Object's hashCode method.
-
-We get the following code:
-<pre>
- @Override
- public @Nullable Packet getChildPacket() {
- return fChildPacket;
- }
-
- @Override
- public @Nullable ByteBuffer getPayload() {
- return fPayload;
- }
-
- /**
- * Getter method that returns the UDP Source Port.
- *
- * @return The source Port.
- */
- public int getSourcePort() {
- return fSourcePort;
- }
-
- /**
- * Getter method that returns the UDP Destination Port.
- *
- * @return The destination Port.
- */
- public int getDestinationPort() {
- return fDestinationPort;
- }
-
- /**
- * {@inheritDoc}
- *
- * See http://www.iana.org/assignments/service-names-port-numbers/service-
- * names-port-numbers.xhtml or
- * http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers
- */
- @Override
- protected @Nullable Packet findChildPacket() throws BadPacketException {
- // When more protocols are implemented, we can simply do a switch on the fDestinationPort field to find the child packet.
- // For instance, if the destination port is 80, then chances are the HTTP protocol is encapsulated. We can create a new HTTP
- // packet (after some verification that it is indeed the HTTP protocol).
- ByteBuffer payload = fPayload;
- if (payload == null) {
- return null;
- }
-
- return new UnknownPacket(getPcapFile(), this, payload);
- }
-
- @Override
- public boolean validate() {
- // Not yet implemented. ATM, we consider that all packets are valid.
- // TODO Implement it. We can compute the real checksum and compare it to fChecksum.
- return true;
- }
-
- @Override
- public UDPEndpoint getSourceEndpoint() {
- @Nullable
- UDPEndpoint endpoint = fSourceEndpoint;
- if (endpoint == null) {
- endpoint = new UDPEndpoint(this, true);
- }
- fSourceEndpoint = endpoint;
- return fSourceEndpoint;
- }
-
- @Override
- public UDPEndpoint getDestinationEndpoint() {
- @Nullable UDPEndpoint endpoint = fDestinationEndpoint;
- if (endpoint == null) {
- endpoint = new UDPEndpoint(this, false);
- }
- fDestinationEndpoint = endpoint;
- return fDestinationEndpoint;
- }
-
- @Override
- public Map<String, String> getFields() {
- ImmutableMap<String, String> map = fFields;
- if (map == null) {
- @SuppressWarnings("null")
- @NonNull ImmutableMap<String, String> newMap = ImmutableMap.<String, String> builder()
- .put("Source Port", String.valueOf(fSourcePort)) //$NON-NLS-1$
- .put("Destination Port", String.valueOf(fDestinationPort)) //$NON-NLS-1$
- .put("Length", String.valueOf(fTotalLength) + " bytes") //$NON-NLS-1$ //$NON-NLS-2$
- .put("Checksum", String.format("%s%04x", "0x", fChecksum)) //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$
- .build();
- fFields = newMap;
- return newMap;
- }
- return map;
- }
-
- @Override
- public String getLocalSummaryString() {
- return "Src Port: " + fSourcePort + ", Dst Port: " + fDestinationPort; //$NON-NLS-1$ //$NON-NLS-2$
- }
-
- @Override
- protected String getSignificationString() {
- return "Source Port: " + fSourcePort + ", Destination Port: " + fDestinationPort; //$NON-NLS-1$ //$NON-NLS-2$
- }
-
- @Override
- public int hashCode() {
- final int prime = 31;
- int result = 1;
- result = prime * result + fChecksum;
- final Packet child = fChildPacket;
- if (child != null) {
- result = prime * result + child.hashCode();
- } else {
- result = prime * result;
- }
- result = prime * result + fDestinationPort;
- final ByteBuffer payload = fPayload;
- if (payload != null) {
- result = prime * result + payload.hashCode();
- } else {
- result = prime * result;
- }
- result = prime * result + fSourcePort;
- result = prime * result + fTotalLength;
- return result;
- }
-
- @Override
- public boolean equals(@Nullable Object obj) {
- if (this == obj) {
- return true;
- }
- if (obj == null) {
- return false;
- }
- if (getClass() != obj.getClass()) {
- return false;
- }
- UDPPacket other = (UDPPacket) obj;
- if (fChecksum != other.fChecksum) {
- return false;
- }
- final Packet child = fChildPacket;
- if (child != null) {
- if (!child.equals(other.fChildPacket)) {
- return false;
- }
- } else {
- if (other.fChildPacket != null) {
- return false;
- }
- }
- if (fDestinationPort != other.fDestinationPort) {
- return false;
- }
- final ByteBuffer payload = fPayload;
- if (payload != null) {
- if (!payload.equals(other.fPayload)) {
- return false;
- }
- } else {
- if (other.fPayload != null) {
- return false;
- }
- }
- if (fSourcePort != other.fSourcePort) {
- return false;
- }
- if (fTotalLength != other.fTotalLength) {
- return false;
- }
- return true;
- }
-</pre>
-
-The UDPPacket class is implemented. We now have the define the UDPEndpoint.
-
-=== Creating the UDPEndpoint ===
-
-For the UDP protocol, an endpoint will be its source or its destination port, depending if it is the source endpoint or destination endpoint. Knowing that, we can create our UDPEndpoint class.
-
-We create in our package a new class named UDPEndpoint that extends ProtocolEndpoint. We also add a field: fPort, which contains the source or destination port. We finally add a constructor public ExampleEndpoint(Packet packet, boolean isSourceEndpoint):
-* ''Packet'' '''packet''': the packet to build the endpoint from.
-* ''boolean'' '''isSourceEndpoint''': whether the endpoint is the source endpoint or destination endpoint.
-
-We obtain the following unimplemented class:
-
-<pre>
-package org.eclipse.linuxtools.pcap.core.protocol.udp;
-
-import org.eclipse.linuxtools.internal.pcap.core.endpoint.ProtocolEndpoint;
-import org.eclipse.linuxtools.internal.pcap.core.packet.Packet;
-
-public class UDPEndpoint extends ProtocolEndpoint {
-
- private final int fPort;
-
- public UDPEndpoint(Packet packet, boolean isSourceEndpoint) {
- super(packet, isSourceEndpoint);
- // TODO Auto-generated constructor stub
- }
-
- @Override
- public int hashCode() {
- // TODO Auto-generated method stub
- return 0;
- }
-
- @Override
- public boolean equals(Object obj) {
- // TODO Auto-generated method stub
- return false;
- }
-
- @Override
- public String toString() {
- // TODO Auto-generated method stub
- return null;
- }
-
-}
-</pre>
-
-For the constructor, we simply initialize fPort. If isSourceEndpoint is true, then we take packet.getSourcePort(), else we take packet.getDestinationPort().
-
-<pre>
- /**
- * Constructor of the {@link UDPEndpoint} class. It takes a packet to get
- * its endpoint. Since every packet has two endpoints (source and
- * destination), the isSourceEndpoint parameter is used to specify which
- * endpoint to take.
- *
- * @param packet
- * The packet that contains the endpoints.
- * @param isSourceEndpoint
- * Whether to take the source or the destination endpoint of the
- * packet.
- */
- public UDPEndpoint(UDPPacket packet, boolean isSourceEndpoint) {
- super(packet, isSourceEndpoint);
- fPort = isSourceEndpoint ? packet.getSourcePort() : packet.getDestinationPort();
- }
-</pre>
-
-Then we implement the methods:
-* ''public int'' '''hashCode()''': method that returns an integer based on the fields value. In our case, it will return an integer depending on fPort, and the parent endpoint that we can retrieve with getParentEndpoint().
-* ''public boolean'' '''equals(Object obj)''': method that returns true if two objects are equals. In our case, two UDPEndpoints are equal if they both have the same fPort and have the same parent endpoint that we can retrieve with getParentEndpoint().
-* ''public String'' '''toString()''': method that returns a description of the UDPEndpoint as a string. In our case, it will be a concatenation of the string of the parent endpoint and fPort as a string.
-
-<pre>
- @Override
- public int hashCode() {
- final int prime = 31;
- int result = 1;
- ProtocolEndpoint endpoint = getParentEndpoint();
- if (endpoint == null) {
- result = 0;
- } else {
- result = endpoint.hashCode();
- }
- result = prime * result + fPort;
- return result;
- }
-
- @Override
- public boolean equals(@Nullable Object obj) {
- if (this == obj) {
- return true;
- }
- if (!(obj instanceof UDPEndpoint)) {
- return false;
- }
-
- UDPEndpoint other = (UDPEndpoint) obj;
-
- // Check on layer
- boolean localEquals = (fPort == other.fPort);
- if (!localEquals) {
- return false;
- }
-
- // Check above layers.
- ProtocolEndpoint endpoint = getParentEndpoint();
- if (endpoint != null) {
- return endpoint.equals(other.getParentEndpoint());
- }
- return true;
- }
-
- @Override
- public String toString() {
- ProtocolEndpoint endpoint = getParentEndpoint();
- if (endpoint == null) {
- @SuppressWarnings("null")
- @NonNull String ret = String.valueOf(fPort);
- return ret;
- }
- return endpoint.toString() + '/' + fPort;
- }
-</pre>
-
-=== Registering the UDP protocol ===
-
-The last step is to register the new protocol. There are three places where the protocol has to be registered. First, the parser has to know that a new protocol has been added. This is defined in the enum org.eclipse.linuxtools.pcap.core.protocol.PcapProtocol. Simply add the protocol name here, along with a few arguments:
-* ''String'' '''longname''', which is the long version of name of the protocol. In our case, it is "User Datagram Protocol".
-* ''String'' '''shortName''', which is the shortened name of the protocol. In our case, it is "UDP".
-* ''Layer'' '''layer''', which is the layer to which the protocol belongs in the OSI model. In our case, this is the layer 4.
-* ''boolean'' '''supportsStream''', which defines whether or not the protocol supports packet streams. In our case, this is set to true.
-
-Thus, the following line is added in the PcapProtocol enum:
-<pre>
- UDP("User Datagram Protocol", "udp", Layer.LAYER_4, true),
-</pre>
-
-Also, TMF has to know about the new protocol. This is defined in org.eclipse.linuxtools.tmf.pcap.core.protocol.TmfPcapProtocol. We simply add it, with a reference to the corresponding protocol in PcapProtocol. Thus, the following line is added in the TmfPcapProtocol enum:
-<pre>
- UDP(PcapProtocol.UDP),
-</pre>
-
-You will also have to update the ''ProtocolConversion'' class to register the protocol in the switch statements. Thus, for UDP, we add:
-<pre>
- case UDP:
- return TmfPcapProtocol.UDP;
-</pre>
-and
-<pre>
- case UDP:
- return PcapProtocol.UDP;
-</pre>
-
-Finally, all the protocols that could be the parent of the new protocol (in our case, IPv4 and IPv6) have to be notified of the new protocol. This is done by modifying the findChildPacket() method of the packet class of those protocols. For instance, in IPv4Packet, we add a case in the switch statement of findChildPacket, if the Protocol number matches UDP's protocol number at the network layer:
-<pre>
- @Override
- protected @Nullable Packet findChildPacket() throws BadPacketException {
- ByteBuffer payload = fPayload;
- if (payload == null) {
- return null;
- }
-
- switch (fIpDatagramProtocol) {
- case IPProtocolNumberHelper.PROTOCOL_NUMBER_TCP:
- return new TCPPacket(getPcapFile(), this, payload);
- case IPProtocolNumberHelper.PROTOCOL_NUMBER_UDP:
- return new UDPPacket(getPcapFile(), this, payload);
- default:
- return new UnknownPacket(getPcapFile(), this, payload);
- }
- }
-</pre>
-
-The new protocol has been added. Running TMF should work just fine, and the new protocol is now recognized.
-
-== Adding stream-based views ==
-
-To add a stream-based View, simply monitor the TmfPacketStreamSelectedSignal in your view. It contains the new stream that you can retrieve with signal.getStream(). You must then make an event request to the current trace to get the events, and use the stream to filter the events of interest. Therefore, you must also monitor TmfTraceOpenedSignal, TmfTraceClosedSignal and TmfTraceSelectedSignal. Examples of stream-based views include a view that represents the packets as a sequence diagram, or that shows the TCP connection state based on the packets SYN/ACK/FIN/RST flags. A (very very very early) draft of such a view can be found at https://git.eclipse.org/r/#/c/31054/.
-
-== TODO ==
-
-* Add more protocols. At the moment, only four protocols are supported. The following protocols would need to be implemented: ARP, SLL, WLAN, USB, IPv6, ICMP, ICMPv6, IGMP, IGMPv6, SCTP, DNS, FTP, HTTP, RTP, SIP, SSH and Telnet. Other VoIP protocols would be nice.
-* Add a network graph view. It would be useful to produce graphs that are meaningful to network engineers, and that they could use (for presentation purpose, for instance). We could use the XML-based analysis to do that!
-* Add a Stream Diagram view. This view would represent a stream as a Sequence Diagram. It would be updated when a TmfNewPacketStreamSignal is thrown. It would be easy to see the packet exchange and the time delta between each packet. Also, when a packet is selected in the Stream Diagram, it should be selected in the event table and its content should be shown in the Properties View. See https://git.eclipse.org/r/#/c/31054/ for a draft of such a view.
-* Make adding protocol more "plugin-ish", via extension points for instance. This would make it easier to support new protocols, without modifying the source code.
-* Control dumpcap directly from eclipse, similar to how LTTng is controlled in the Control View.
-* Support pcapng. See: http://www.winpcap.org/ntar/draft/PCAP-DumpFileFormat.html for the file format.
-* Add SWTBOT tests to org.eclipse.linuxtools.tmf.pcap.ui
-* Add a Raw Viewer, similar to Wireshark. We could use the “Show Raw” in the event editor to do that.
-* Externalize strings in org.eclipse.linuxtools.pcap.core. At the moment, all the strings are hardcoded. It would be good to externalize them all.
+++ /dev/null
-###############################################################################
-# Copyright (c) 2013, 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-Bundle-Vendor = Eclipse Trace Compass
-Bundle-Name = Trace Compass TMF Help Plug-in
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<plugin>
-<!-- This part should be in a documentation plugin -->
-<!-- Configure the help contribution for this plugin -->
- <extension point="org.eclipse.help.toc">
- <toc
- file="doc/Developer-Guide-toc.xml"
- primary="true" />
- </extension>
-</plugin>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (C) 2011, Red Hat, Inc.
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <artifactId>org.eclipse.tracecompass</artifactId>
- <groupId>org.eclipse.tracecompass</groupId>
- <version>0.1.0-SNAPSHOT</version>
- </parent>
-
- <artifactId>org.eclipse.tracecompass.tmf.help</artifactId>
- <version>0.1.0-SNAPSHOT</version>
- <packaging>eclipse-plugin</packaging>
-
- <name>Trace Compass TMF Help Plug-in</name>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-antrun-plugin</artifactId>
- <executions>
- <execution>
- <id>generate-documentation</id>
- <phase>generate-sources</phase>
- <configuration>
- <echo>Generating TMF Help Files</echo>
- <target>
- <property name="compile_classpath" refid="maven.compile.classpath" />
- <ant target="build" inheritRefs="true" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- <execution>
- <id>clean-documentation</id>
- <phase>clean</phase>
- <configuration>
- <echo>Cleaning up generated TMF Help Files</echo>
- <target>
- <ant target="clean" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- </executions>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-launcher</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-nodeps</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- </dependencies>
- </plugin>
- </plugins>
- </build>
-
- <groupId>org.eclipse.tracecompass</groupId>
-</project>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType">
-<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_CLEAN_TARGETS" value="clean,"/>
-<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/>
-<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/>
-<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${working_set:<?xml version="1.0" encoding="UTF-8"?> <resources> <item path="/org.eclipse.tracecompass.tmf.pcap.help" type="4"/> </resources>}"/>
-<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_PATHS">
-<listEntry value="/org.eclipse.tracecompass.tmf.pcap.help/build.xml"/>
-</listAttribute>
-<listAttribute key="org.eclipse.debug.core.MAPPED_RESOURCE_TYPES">
-<listEntry value="1"/>
-</listAttribute>
-<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/>
-<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.tracecompass.tmf.pcap.help"/>
-<stringAttribute key="org.eclipse.jdt.launching.SOURCE_PATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.tracecompass.tmf.pcap.help/build.xml}"/>
-<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="incremental,clean"/>
-<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/>
-<stringAttribute key="process_factory_id" value="org.eclipse.ant.ui.remoteAntProcessFactory"/>
-</launchConfiguration>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<projectDescription>
- <name>org.eclipse.tracecompass.tmf.pcap.help</name>
- <comment></comment>
- <projects>
- </projects>
- <buildSpec>
- <buildCommand>
- <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name>
- <triggers>clean,full,incremental,</triggers>
- <arguments>
- <dictionary>
- <key>LaunchConfigHandle</key>
- <value><project>/.externalToolBuilders/org.eclipse.linuxtools.tmf.pcap.help build.xml [Builder].launch</value>
- </dictionary>
- <dictionary>
- <key>incclean</key>
- <value>true</value>
- </dictionary>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.ManifestBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- <buildCommand>
- <name>org.eclipse.pde.SchemaBuilder</name>
- <arguments>
- </arguments>
- </buildCommand>
- </buildSpec>
- <natures>
- <nature>org.eclipse.pde.PluginNature</nature>
- <nature>org.eclipse.mylyn.wikitext.ui.wikiTextNature</nature>
- </natures>
-</projectDescription>
+++ /dev/null
-eclipse.preferences.version=1
-encoding/<project>=UTF-8
+++ /dev/null
-eclipse.preferences.version=1
-line.separator=\n
+++ /dev/null
-eclipse.preferences.version=1
-org.eclipse.ltk.core.refactoring.enable.project.refactoring.history=false
+++ /dev/null
-Manifest-Version: 1.0
-Bundle-ManifestVersion: 2
-Bundle-Name: %Bundle-Name
-Bundle-Vendor: %Bundle-Vendor
-Bundle-Version: 0.1.0.qualifier
-Bundle-Localization: plugin
-Bundle-SymbolicName: org.eclipse.tracecompass.tmf.pcap.help;singleton:=true
-Require-Bundle: org.eclipse.help
+++ /dev/null
-This describes how to build the documentation found in the o.e.t.tmf.pcap.help
-plugin.
-
-
-Your Eclipse environment first needs to have the "Mylyn Wikitext" plugin
-installed. It can be found in the default Eclipse repository, under
-"Collaboration".
-
-Once that is installed, you should be able to use the manual Eclipse builder to
-generate the doc : select the tmf.pcap.help plugin and choose, in the top-menu,
-"Project -> Build Project".
-
-It uses the build.xml Ant script, but it's recommended to run it from within
-Eclipse, since the builder will pass some environment variables that the script
-needs.
-
-You might get a warning from build.properties because of a missing file. This
-file gets generated with the rest of the doc, so once you have run these steps
-(and refreshed the project if needed), the warning should disappear.
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"/>
-<title>About</title>
-</head>
-<body lang="EN-US">
-<h2>About This Content</h2>
-
-<p>June 5, 2006</p>
-<h3>License</h3>
-
-<p>The Eclipse Foundation makes available all content in this plug-in ("Content"). Unless otherwise
-indicated below, the Content is provided to you under the terms and conditions of the
-Eclipse Public License Version 1.0 ("EPL"). A copy of the EPL is available
-at <a href="http://www.eclipse.org/legal/epl-v10.html">http://www.eclipse.org/legal/epl-v10.html</a>.
-For purposes of the EPL, "Program" will mean the Content.</p>
-
-<p>If you did not receive this Content directly from the Eclipse Foundation, the Content is
-being redistributed by another party ("Redistributor") and different terms and conditions may
-apply to your use of any object code in the Content. Check the Redistributor's license that was
-provided with the Content. If no such license exists, contact the Redistributor. Unless otherwise
-indicated below, the terms and conditions of the EPL still apply to any source code in the Content
-and such source code may be obtained at <a href="http://www.eclipse.org/">http://www.eclipse.org</a>.</p>
-
-</body>
-</html>
\ No newline at end of file
+++ /dev/null
-/* following font face declarations need to be removed for DBCS */
-
-
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-family: Arial, sans-serif; color: #000000}
-pre { font-family: Courier, monospace}
-
-/* end font face declarations */
-
-/* following font size declarations should be OK for DBCS */
-body, h1, h2, h3, h4, p, table, td, caption, th, ul, ol, dl, li, dd, dt {font-size: 12pt; }
-pre { font-size: 12pt}
-
-/* end font size declarations */
-
-body { background: #FFFFFF}
-h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 }
-h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 }
-h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 }
-h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic }
-h5 { font size: 13.5pt; }
-p { font-size: 12pt; }
-pre { margin-left: 6; font-size: 9pt }
-
-a:link { color: #006699 }
-a:visited { color: #996699 }
-a:hover { color: #006699 }
-
-ul { margin-top: 0; margin-bottom: 10 }
-li { margin-top: 0; margin-bottom: 0 }
-li p { margin-top: 0; margin-bottom: 0 }
-ol { margin-top: 0; margin-bottom: 10 }
-dl { margin-top: 0; margin-bottom: 10 }
-dt { margin-top: 0; margin-bottom: 0; font-weight: bold }
-dd { margin-top: 0; margin-bottom: 0 }
-strong { font-weight: bold}
-em { font-style: italic}
-var { font-style: italic}
-div.revision { border-left-style: solid; border-left-width: thin;
- border-left-color: #7B68EE; padding-left:5 }
-th { font-weight: bold }
-.hidden {
- display: none;
-}
-
-/* Mike Behm's addition to the style sheet */
-.userinput { font-family: monospace; }
-.guitab, .important, .guibutton, .selectblue, .guimenu, .guilabel,
-.notetitle {
- color: #000000;
- font-family: helvetica, arial, sans-serif;
- font-weight: bold;
- }
-div.linux {display:none;}
-.firsterm {font-style:italic;}
-
-.typewriter {font-family:monospace;}
-.bold {font-weight:600;}
-.linethrough {text-decoration: line-through;}
-.underline {text-decoration: underline;}
+++ /dev/null
-###############################################################################
-# Copyright (c) 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-bin.includes = plugin.xml,\
- META-INF/,\
- about.html,\
- plugin.properties,\
- book.css,\
- doc/
-jars.extra.classpath = platform:/plugin/org.eclipse.mylyn.wikitext.core,\
- platform:/plugin/org.eclipse.mylyn.wikitext.mediawiki.core
-src.includes = about.html
-
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<project name="org.eclipse.linuxtools.tmf.pcap.help" default="build" basedir=".">
- <description>
- Generate Eclipse help content for the Linux Tools Pcap User Guide
- </description>
-
- <property name="ug.title" value="Pcap Network Tracing User Guide" />
-
- <path id="wikitext.tasks.classpath">
- <!-- Search in the local Eclipse plugins directory for the Wikitext plugin -->
- <fileset dir="${osgi.syspath}" erroronmissingdir="false">
- <include name="org.eclipse.mylyn.wikitext.*core*.jar" />
- <include name="com.google.guava_*.jar" />
- </fileset>
-
- <!-- For Maven builds: use the compile_classpath -->
- <pathelement path="${compile_classpath}" />
- </path>
-
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties" />
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
- <!-- Different location in more recent versions of Mylyn (Luna ?) -->
- <taskdef classpathref="wikitext.tasks.classpath" resource="org/eclipse/mylyn/wikitext/core/ant/tasks.properties" />
-
- <target name="build" description="Generate Eclipse help content for the Linux Tools Pcap User Guide">
- <wikitext-to-eclipse-help markupLanguage="MediaWiki"
- validate="true"
- failonvalidationerror="true"
- overwrite="true"
- multipleOutputFiles="true"
- navigationimages="true"
- title="${ug.title}"
- formatoutput="true"
- helpPrefix="doc">
- <fileset dir="doc">
- <include name="User-Guide.mediawiki" />
- </fileset>
- <stylesheet url="book.css" />
- </wikitext-to-eclipse-help>
- <antcall target="test" />
- </target>
-
- <target name="test" description="Verify that all of the HTML files are well-formed XML">
- <!--
- Don't bother with DTD validation: we only care if the files are well-formed.
- We therefore provide an empty DTD
- -->
- <xmlvalidate lenient="true">
- <fileset dir="doc">
- <include name="**/*.html" />
- </fileset>
- <dtd publicid="-//W3C//DTD XHTML 1.0 Transitional//EN" location=".empty.dtd" />
- </xmlvalidate>
- </target>
-
- <target name ="clean" description="Delete all generated files">
- <delete failonerror="false">
- <fileset dir="doc" includes="**/*.html" />
- <fileset dir="doc" includes="**/*.xml" />
- </delete>
- </target>
-
-</project>
+++ /dev/null
-*.html
-*.xml
+++ /dev/null
-= Pcap Support Within TMF =
-
-TMF now supports the reading of libpcap files for network tracing. Those files contains packets that were seen on a network, have a .pcap or .cap extension and can be captured with tools like Wireshark/Tshark/Tcpdump. To open a libpcap trace, simply import it just like any other trace type and TMF will recognize the format. Open the imported trace to see the packets that were captured. For more information about generic features of TMF see the [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide User Guide].
-
-== Supported Protocols ==
-
-Currently, the Pcap integration in TMF can only recognize four protocols: Ethernet, Internet Protocol Version 4, TCP and UDP. In the future, more protocols will be added and supported. If you want to contribute, please see the “Adding a protocol” section in the [http://wiki.eclipse.org/Linux_Tools_Project/TMF/User_Guide TMF Developer Guide].
-
-== Network Tracing Perspective ==
-
-To help analyze the network traces, a new perspective has been created: the Network Tracing perspective. It looks a lot like Wireshark (since it is the de-facto standard) and contains all the views that are useful for network trace analysis. Those views are:
-* '''Event editor''': A high-level view of all the packets. It lists all the packets and gives basic information about them, like source, destination, timestamp, protocol, etc.
-* '''Properties View''': A low-level view of a particular packet. Once a packet is selected in the event editor, all its fields appear in the properties view.
-* '''Histogram View''': A distribution of the packets relative to time. This allows to identify the period where the network was the most solicited, for instance.
-* '''Statistics View''': A view of the different packet type present in the trace.
-* '''Colors View''': A view used to color the events in the event editor. This is useful for rapidly identifying packet type visually. By default, no event are colored.
-* '''Filter View''': A view used to filter the packets for easier analysis.
-* '''Stream List View''': A view that list all the stream present in the trace/experiment. A stream is a bidirectional flow of packets (a conversation) between two endpoints. An endpoint is either the source or the destination of a packet (which is protocol-dependent).
-
-To open the perspective, select '''Window''' > '''Open Perspective''' > '''Other...''' > '''Network Tracing'''.
-
-[[Image:images/networkTracingPerspective.png|The Network Tracing Perspective]]
-
-== Filtering On Subfield ==
-
-It is now possible to filter on subfields, which is really useful for pcap traces. To do so, in the field combo of the Filter View, start with a slash and type the subfield path by separating the different level with a slash. For instance, to get the Source IP Address of the Internet Protocol Version 4, type:
-
-''/Internet Protocol Version 4/Source IP Address''
-
-If a field name contains a real slash, type “\/” (backslash-slash) instead to make an uninterpreted slash. For instance, to get the field named “Process/Thread”, type:
-
-''/Process\/Thread''
-
-[[Image:images/subfieldFiltering.png|Example of filtering on subfields]]
-
-== Stream List View ==
-
-Most of the time, you want to analyze the conversation between two endpoints (a stream). The stream list view allows you to do just that, by isolating the interesting packets. The Stream List View is updated when a new pcap trace is opened and lists all the different streams present in the trace/experiment, for all the supported protocols. By right-clicking on a stream, you can follow a stream, which will send a TmfNewPacketStreamSignal that can be used by other views to run an analysis on the stream. You can also extract the stream as a filter, which will generate a filter based on the stream attributes. It is then possible to customize that filter and apply it on the event editor to get the interesting packets.
-
-[[Image:images/streamListView.png|Example of Stream List View]]
-
-== Limitations ==
-
-* No version check. It assumes the version is 2.4 (which is safe enough, since the format hasn't changed for 10+ years and is not supposed to change anytime soon.
-* All timestamps are assumed to be in GMT time.
-
-== References ==
-
-
-* [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng2/User_Guide LTTng User Guide]
-* [http://wiki.eclipse.org/Linux_Tools_Project/TMF/User_Guide TMF Developer Guide]
-
+++ /dev/null
-###############################################################################
-# Copyright (c) 2014 Ericsson
-#
-# All rights reserved. This program and the accompanying materials
-# are made available under the terms of the Eclipse Public License v1.0
-# which accompanies this distribution, and is available at
-# http://www.eclipse.org/legal/epl-v10.html
-#
-# Contributors:
-# Ericsson - Initial API and implementation
-###############################################################################
-
-Bundle-Vendor = Eclipse Trace Compass
-Bundle-Name = Trace Compass Pcap Help Plug-in
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<plugin>
-<!-- This part should be in a documentation plugin -->
-<!-- Configure the help contribution for this plugin -->
- <extension point="org.eclipse.help.toc">
- <toc
- file="doc/User-Guide-toc.xml"
- primary="true" />
- </extension>
-</plugin>
+++ /dev/null
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
- Copyright (C) 2014, Ericsson
-
- All rights reserved. This program and the accompanying materials
- are made available under the terms of the Eclipse Public License v1.0
- which accompanies this distribution, and is available at
- http://www.eclipse.org/legal/epl-v10.html
--->
-<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <artifactId>org.eclipse.tracecompass</artifactId>
- <groupId>org.eclipse.tracecompass</groupId>
- <version>0.1.0-SNAPSHOT</version>
- </parent>
-
- <artifactId>org.eclipse.tracecompass.tmf.pcap.help</artifactId>
- <version>0.1.0-SNAPSHOT</version>
- <packaging>eclipse-plugin</packaging>
-
- <name>Trace Compass Pcap Help Plug-in</name>
-
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-antrun-plugin</artifactId>
- <executions>
- <execution>
- <id>generate-documentation</id>
- <phase>generate-sources</phase>
- <configuration>
- <echo>Generating Pcap Help Files</echo>
- <target>
- <property name="compile_classpath" refid="maven.compile.classpath" />
- <ant target="build" inheritRefs="true" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- <execution>
- <id>clean-documentation</id>
- <phase>clean</phase>
- <configuration>
- <echo>Cleaning up generated Pcap Help Files</echo>
- <target>
- <ant target="clean" antfile="build.xml" />
- </target>
- </configuration>
- <goals>
- <goal>run</goal>
- </goals>
- </execution>
- </executions>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-launcher</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- <dependency>
- <groupId>org.apache.ant</groupId>
- <artifactId>ant-nodeps</artifactId>
- <version>1.8.1</version>
- </dependency>
-
- </dependencies>
- </plugin>
- </plugins>
- </build>
-
- <groupId>org.eclipse.tracecompass</groupId>
-</project>
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.tmf.pcap.help"
+ id="org.eclipse.tracecompass.tmf.pcap.doc.user"
download-size="0"
install-size="0"
version="0.0.0"/>
unpack="false"/>
<plugin
- id="org.eclipse.tracecompass.tmf.help"
+ id="org.eclipse.tracecompass.doc.dev"
download-size="0"
install-size="0"
version="0.0.0"/>
</profiles>
<modules>
+ <module>doc</module>
+
<module>org.eclipse.tracecompass.common.core</module>
<module>org.eclipse.tracecompass.btf</module>
<module>org.eclipse.tracecompass.tmf.ui</module>
<module>org.eclipse.tracecompass.tmf.ui.tests</module>
<module>org.eclipse.tracecompass.tmf.ui.swtbot.tests</module>
- <module>org.eclipse.tracecompass.tmf.help</module>
<module>org.eclipse.tracecompass.tmf.ctf</module>
<module>org.eclipse.tracecompass.tmf.ctf.core</module>
<module>org.eclipse.tracecompass.tmf.pcap.core.tests</module>
<module>org.eclipse.tracecompass.tmf.pcap.ui</module>
<module>org.eclipse.tracecompass.tmf.pcap.ui.swtbot.tests</module>
- <module>org.eclipse.tracecompass.tmf.pcap.help</module>
<module>org.eclipse.tracecompass.tmf.analysis.xml.core</module>
<module>org.eclipse.tracecompass.tmf.analysis.xml.core.tests</module>
<module>org.eclipse.tracecompass.tmf.analysis.xml.ui</module>
<module>org.eclipse.tracecompass.tmf.analysis.xml.ui.tests</module>
- <module>org.eclipse.tracecompass.help</module>
<module>org.eclipse.tracecompass.releng-site</module>
<module>org.eclipse.tracecompass.target</module>
<module>org.eclipse.tracecompass.testing</module>
<module>org.eclipse.tracecompass.gdbtrace.core.tests</module>
<module>org.eclipse.tracecompass.gdbtrace.ui</module>
<module>org.eclipse.tracecompass.gdbtrace.ui.tests</module>
- <module>org.eclipse.tracecompass.gdbtrace.help</module>
<module>org.eclipse.tracecompass.rcp.branding</module>
<module>org.eclipse.tracecompass.rcp.branding.feature</module>
<module>org.eclipse.tracecompass.rcp</module>
- <module>org.eclipse.tracecompass.rcp.help</module>
<module>org.eclipse.tracecompass.rcp.ui</module>
<module>org.eclipse.tracecompass.examples</module>
projects / deliverable / tracecompass.git / commitdiff
