= 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.
+Trace Compass is a Java tool for viewing and analyzing any type of logs or traces. Its goal is to provide views, graphs, metrics, etc. to help extract useful information from traces, in a way that is more user-friendly and informative than huge text dumps.
== About Tracing ==
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 ==
+== Features ==
-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.
+Trace Compass 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
-The LTTng Eclipse plug-in provides the following views:
+There is also support for the integration of non-LTTng trace types:
-* ''Project'' - an extension to the standard Eclipse Project view tailored for tracing projects
-* ''Control'' - to control the tracer and configure the tracepoints
+* 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)
+
+Trace Compass provides the following main views:
+
+* ''Project Explorer'' - an extension to the standard Eclipse Project view tailored for tracing projects
* ''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:
+== LTTng integration ==
+
+One of the main features of Trace Compass is the LTTng integration. 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.
+
+The LTTng plug-ins provide an 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.
+
+At present, the LTTng plug-ins support 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:
+Also, the LTTng plug-ins 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:
+Finally, the LTTng plug-ins supports the following Control views:
+* ''Control'' - to control the tracer and configure the tracepoints
-* 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)
+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.
= Installation =
-This section describes the installation of the LTTng tracer and the LTTng Eclipse plug-ins as well as their dependencies.
+This section describes the installation of the LTTng tracer and the Trace Compass plug-ins as well as their dependencies.
== LTTng Tracer ==
'''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 ==
+== Trace Compass 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 easiest way to install the Trace Compass plug-ins for Eclipse is through the Install New Software menu. For information on how to use this menu, refer to this [http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.platform.doc.user%2Ftasks%2Ftasks-124.htm link].
-The LTTng plug-ins are structured as a stack of features/plug-ins as following:
+The Trace Compass main 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
+** ''Feature'': org.eclipse.tracecompass.ctf
+** ''Plug-ins'': org.eclipse.tracecompass.ctf.core, org.eclipse.tracecompass.ctf.parser
* '''State System Core''' - State system for TMF
-** ''Plug-ins'': org.eclipse.linuxtools.statesystem.core
+** ''Plug-ins'': org.eclipse.tracecompass.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
+** ''Feature'': org.eclipse.tracecompass.tmf
+** ''Plug-ins'': org.eclipse.tracecompass.tmf.core, org.eclipse.tracecompass.tmf.ui. org.eclipse.tracecompass.tmf.analysis.xml.core, org.eclipse.tracecompass.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
+** ''Feature'': org.eclipse.tracecompass.tmf.ctf
+** ''Plug-ins'': org.eclipse.tracecompass.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 Control''' - The wrapper for the LTTng tracer control. Can be used for kernel or application tracing.
+** ''Feature'': org.eclipse.tracecompass.lttng2.control
+** ''Plug-ins'': org.eclipse.tracecompass.lttng2.control.core, org.eclipse.tracecompass.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
+** ''Feature'': org.eclipse.tracecompass.lttng2.kernel
+** ''Plug-ins'': org.eclipse.tracecompass.analysis.os.linux.core, org.eclipse.tracecompass.analysis.os.linux.ui, org.eclipse.tracecompass.lttng2.kernel.core, org.eclipse.tracecompass.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
+** ''Feature'': org.eclipse.tracecompass.lttng2.ust
+** ''Plug-ins'': org.eclipse.tracecompass.lttng2.ust.core, org.eclipse.tracecompass.lttng2.ust.ui
-== LTTng Eclipse Dependencies ==
+== LTTng Control 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.
+The Eclipse LTTng Control feature 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.
+When using ''ssh'', 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'').
+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 are installed for you as a dependency of the LTTng Control feature. If necessary, it can be installed manually with 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.
+If you do not have any traces, sample LTTng traces can be found here [http://lttng.org/files/samples]. This page contains links to some sample LTTng 2.0 kernel traces. The trace needs to be uncompressed to be opened. The traces can also be imported directly as archive, see the [[#Importing|Importing]] section for more detail.
-Here are the quick steps to verify that your installation is functional:
+Here are the quick steps to verify that your installation is functional using a LTTng trace:
* Start Eclipse
* Open the LTTng perspective
* Create a Tracing project
-** Right-click in the Project view and select "New Project"
+** Right-click in the Project Explorer view and select New, Tracing 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
+* Open and visualize 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 =
+= Trace Compass Main Features =
== Tracing Perspective ==
-The '''Tracing''' perspective is part of the '''Tracing and Monitoring Framework (TMF)''' and groups the following views:
+The '''Tracing''' perspective is part of the '''Tracing and Monitoring Framework (TMF)''' and groups the following views:
-* [[#Project_View | Project View]]
+* [[#Project Explorer_View | Project Explorer View]]
* [[#Events_Editor | Events Editor]]
* [[#Histogram_View | Histogram View]]
* [[#Statistics_View | Statistics View]]
[[Image:images/ShowTracingViews.png]]
-Additionally, the '''LTTng''' feature provides an '''LTTng Tracer Control''' functionality. It comes with a dedicated '''Control View'''.
+Additionally, the '''LTTng Control''' feature provides an '''LTTng Tracer Control''' functionality. It comes with a dedicated '''Control View'''.
* [[#LTTng_Tracer_Control | LTTng Tracer Control]]
-== Project View ==
+== Project Explorer 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.
+The Project Explorer 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 ===
[[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.
+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. If the selected files include archive files (tar, zip), they will be extracted automatically and imported as well.
-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.
+Traces can also be imported directly 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>'''.
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.
+The option '''Create Experiment''' will create an experiment with all imported traces. By default, the experiment name is the '''Root directory''' name, when importing from directory, or the ''' Archive file''' name, when importing from archive. One can change the experiment name by typing a new name in the text box beside the option.
+
[[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).
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.
+=== Refreshing of Trace and Trace Folder ===
+Traces and trace folders in the workspace might be updated on the media. To refresh the content, right-click the trace or trace folder and select menu item '''Refresh'''. Alternatively, select the trace or trace folder and press key '''F5'''.
+
+=== Remote Fetching ===
+
+It is possible to import traces automatically from one or more remote hosts according to a predefined remote profile by using the '''Fetch Remote Traces''' wizard.
+
+To start the wizard, right-click on a target trace folder and select '''Fetch Remote Traces...'''.
+
+[[Image:images/FetchRemoteTracesMenu.png]]
+
+The wizard opens on the '''Remote Profile''' page.
+
+[[Image:images/RemoteProfileWizardPageBlank.png]]
+
+If the remote profile already exists, it can be selected in the '''Profile name''' combo box. Otherwise, click '''Manage Profiles''' to open the '''Remote Profiles''' preferences page.
+
+==== Remote Profile elements ====
+
+[[Image:images/RemoteProfilesPreferencesPage.png]]
+
+Click '''Add''' to create a new remote profile. A default remote profile template appears.
+
+[[Image:images/RemoteProfilesPreferencesPageDefault.png]]
+
+===== Profile =====
+
+Edit the '''Profile name''' field to give a unique name to the new profile.
+
+Under the Profile element, at least one Connection Node element must be defined.
+
+===== Connection Node =====
+
+'''Node name''': Unique name for the connection within the scope of the Remote Services provider.
+
+'''URI''': URI for the connection. Its scheme maps to a particular Remote Services provider. If the connection name already exists for that provider, the URI must match its connection information. The scheme '''ssh''' can be used for the Built-In SSH provider. The scheme '''file''' can be used for the local file system.
+
+To view or edit existing connections, see the '''Remote Development''' > '''Remote Connections''' preferences page. On this page the user can enter a password for the connection.
+
+Under the Connection Node element, at least one Trace Group element must be defined.
+
+===== Trace Group =====
+
+'''Root path''': The absolute root path from where traces will be fetched. For example, ''/home/user'' or ''/C/Users/user''.
+
+'''Recursive''': Check this box to search for traces recursively in the root path.
+
+Under the Trace Group element, at least one Trace element must be defined.
+
+===== Trace =====
+
+'''File pattern''': A regular expression pattern to match against the file name of traces found under the root path. If the '''Recursive''' option is used, the pattern must match against the relative path of the trace, using forward-slash as a path separator. Files that do not match this pattern are ignored. If multiple Trace elements have a matching pattern, the first matching element will be used, and therefore the most specific patterns should be listed first. Following are some pattern examples:
+
+* <pre><nowiki>.*</nowiki></pre> matches any trace in any folder
+* <pre><nowiki>[^/]*\.log</nowiki></pre> matches traces with .log extension in the root path folder
+* <pre><nowiki>.*\.log</nowiki></pre> matches traces with .log extension in any folder
+* <pre><nowiki>folder-[^/]*/[^/]*\.log</nowiki></pre> matches traces with .log extension in folders matching a pattern
+* <pre><nowiki>(.*/)?filename</nowiki></pre> matches traces with a specific name in any folder
+
+'''Trace Type''': The trace type to assign to the traces after fetching, or '''<Automatic Detection>''' to determine the trace type automatically. Note that traces whose trace type can not be assigned according to this setting are not deleted after fetching.
+
+==== Profile editing and management ====
+
+Right-click a profile element to bring up its context menu. A '''New''' child element of the appropriate type can be created. Select '''Delete''' to delete a node, or '''Cut''', '''Copy''' and '''Paste''' to move or copy elements from one profile element to another. The keyboard shortcuts can also be used.
+
+Press the '''Add''' button to create a new element of the same type and following the selected element, or a new profile if the selection is empty.
+
+Press the '''Remove''' button to delete the selected profile elements.
+
+Press the '''Import''' button to import profiles from a previously exported XML file.
+
+Press the '''Export''' button to export the selected profiles to an XML file.
+
+Press the '''Move Up''' or '''Move Down''' buttons to reorder the selected profile element.
+
+The filter text box can be used to filter profiles based on the profile name or connection node.
+
+When the remote profile information is valid and complete, press the '''OK''' button to save the remote profiles preferences.
+
+[[Image:images/RemoteProfilesPreferencesPageFull.png]]
+
+==== Selecting remote traces ====
+
+Back in the '''Remote Profiles''' wizard page, select the desired profile and click '''Next >'''. Clicking '''Finish''' at this point will automatically select and download all matching traces.
+
+[[Image:images/RemoteProfileWizardPageNext.png]]
+
+If required, the selected remote connections are created and connection is established. The user may be prompted for a password. This can be avoided by storing the password for the connection in the '''Remote Connections''' preference page.
+
+[[Image:images/FetchRemoteTracesPassword.png]]
+
+The root path of every Trace Group is scanned for matching files. The result is shown in the '''Remote Traces''' wizard page.
+
+[[Image:images/RemoteTracesWizardPage.png]]
+
+Select the traces to fetch by checking or unchecking the desired connection node, trace group, folder or individual trace. Click '''Finish''' to complete the operation.
+
+If any name conflict occurs, the user will be prompted to rename, overwrite or skip the trace, unless the '''Overwrite existing trace without warning''' option was checked in the '''Remote Profiles''' wizard page.
+
+The downloaded traces will be imported to the initially selected project folder. They will be stored under a folder structure with the pattern ''<connection name>/<path>/<trace name>'' where the path is the trace's remote path relative to its trace group's root path.
+
+[[Image:images/FetchRemoteTracesProject.png]]
+
=== 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'''.
+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 '''Linux Kernel Trace''' and '''Generic CTF trace'''.
[[Image:images/SelectLTTngKernelTraceType.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:
+The columns of the table are defined by the fields (aspects) of the specific trace type. These are the defaults:
* '''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
+* '''Type''': the event type
+* '''Contents''': the fields (or payload) of this event
The first row of the table is the header row a.k.a. the Search and Filter row.
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.
+All matching events will have a 'search match' icon in their left margin. Non-matching events will be dimmed. The characters in each column which match the regular expression will be highlighted.
-[[Image:images/DefaultTmfEvents-Search.png]]
+[[Image:images/TraceEditor-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.
==== 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.
+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. The characters in each column which match the regular expression will be highlighted.
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]]
+[[Image:images/TraceEditor-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.
[[Image:images/Bookmarks.png]]
+=== Copy to Clipboard ===
+
+The text of selected events can be copied to the clipboard by right-clicking on the table and selecting '''Copy to Clipboard''' in the context menu. The clipboard contents will be prefixed by the column header names. For every event in the table selection, the column text will be copied to the clipboard. The column text will be tab-separated. Hidden columns will not be included in the clipboard contents.
+
=== 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.
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.
+=== Refreshing of Trace ===
+It's possible to refresh the content of the trace and resume indexing in case the current open trace was updated on the media. To refresh the trace, right-click into the table and select menu item '''Refresh'''. Alternatively, press key '''F5'''.
+
=== 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.
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.
+=== Customization ===
+
+The table columns can be reordered by the user by dragging the column headers. This column order is saved when the editor is closed. The setting applies to all traces of the same trace type.
+
+The table columns can be hidden or restored by right-clicking on any column header and clicking on an item in the context menu to toggle its state. Clicking '''Show All''' will restore all table columns.
+
+The table font can be customized by the user by changing the preference in '''Window''' > '''Preferences''' > '''General''' > '''Appearance''' > '''Colors and Fonts''' > '''Tracing''' > '''Trace event table font'''.
+
+The search and filter highlight color can be customized by the user by changing the preference in '''Window''' > '''Preferences''' > '''General''' > '''Appearance''' > '''Colors and Fonts''' > '''Tracing''' > '''Trace event table highlight color'''.
+
== 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.
+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. The time axis is aligned with other views that support automatic time axis alignment (see [[#Automatic Time Axis Alignment | Automatic Time Axis Alignment]]).
[[Image:images/HistogramView.png]]
+The '''Align Views''' toggle button [[Image:images/link.gif]] in the local toolbar allows to disable and enable the automatic time axis alignment of time-based views. Disabling the alignment in the Histogram view will disable this feature across all the views because it's a workspace preference.
+
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.
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 smaller (zoom) histogram, on top right, corresponds to the current zoom window, a sub-range of the event set. The window size can be adjusted by dragging the sash left beside the zoom window.
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 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 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 '''TRACETYPE''', '''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 '''TRACETYPE''' node filters against the trace type of the trace as defined in a plug-in extension or in a custom parser. When used, any child node will have its ''type'' combo box fixed and its ''aspect'' combo box restricted to the possible aspects of that trace 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 '''CONTAINS''' node matches when the specified event ''aspect'' 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 ''type'' combo box restricts the possible aspects to those of the specified trace type.
+
+The '''EQUALS''' node matches when the specified event ''aspect'' 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 ''type'' combo box restricts the possible aspects to those of the specified trace type.
+
+The '''MATCHES''' node matches when the specified event ''aspect'' value matches against the specified ''regular expression''. A ''not'' operator can be applied to invert the condition. The ''type'' combo box restricts the possible aspects to those of the specified trace type.
-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 '''COMPARE''' node matches when the specified event ''aspect'' 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. The ''type'' combo box restricts the possible aspects to those of the specified trace type.
-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.
+For numerical comparisons, strings prefixed by "0x", "0X" or "#" are treated as hexadecimal numbers and strings prefixed by "0" are treated as octal numbers.
-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.
+For time stamp comparisons, strings are treated as seconds with or without fraction of seconds. This corresponds to the '''TTT''' format in the '''Time Format''' preferences. The value for a selected event can be found in the '''Properties''' view under the ''Timestamp'' property. The common 'Timestamp' aspect can always be used for time stamp comparisons regardless of its time format.
-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.
+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''.
[[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.
+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. The time axis is aligned with other views that support automatic time axis alignment (see [[#Automatic Time Axis Alignment | Automatic Time Axis Alignment]]).
Time synchronization is enabled between the time chart view and other trace viewers such as the events table.
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.
+The '''Align Views''' toggle button [[Image:images/link.gif]] in the local toolbar allows to disable and enable the automatic time axis alignment of time-based views. Disabling the alignment in the this view will disable this feature across all the views because it's a workspace preference.
+
== 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.
* '''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]
+Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/tracecompass/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:
* '''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]
+Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/tracecompass/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.
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.
+== Automatic Time Axis Alignment ==
+
+Trace Compass supports automatic alignment of the time axis for time base views. The user now can resize the time window of one view and all other open views will align to the new window size and position. The automatic alignment is optional and can be disabled and enabled using the '''Align Views''' toolbar button. Disabling or enabling it in one view it will disable and enable it for all view since it's a workspace wide setting.
+
+[[Image:images/TimeAlignment_sash.png]]
+
= 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.
Refer to chapter [[#Recording a Snapshot | Recording a Snapshot]] for how to create a snapshot.
-=== Creating a Live Tracing Session ====
+=== 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]]
[[Image:images/LTTng2AssignedEvents.png]]
-=== Configuring Filter Expression On UST Event Fields ===
+=== Configuring Filter Expression When Enabling Events ===
-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.
+It is possible to provide a filter expression when enabling events for UST or Kernel. This feature has been available for UST since LTTng v2.1.0 and for Kernel since v2.7.0. To configure a filter expression, open the enable event dialog as described in previous chapters [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]], [[#Enabling Kernel Events On Session Level | Enabling Kernel 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]]. Then configure the relevant events and enter the filter expression in the '''Filter Expression''' text field.
-[[Image:images/LTTng2EnableEventWithFilter.png]]
+[[Image:images/LTTng2EnableEventWithFilter.png]] [[Image:images/LTTng2EnableEventWithKernelFilter.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.
+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]] and enter the filter expression in the '''Filter Expression''' text field.
[[Image:images/LTTng2AssignEventDialogWithFilter.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/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.
+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. The option '''Create Experiment''' will create an experiment with all imported traces. By default, the experiment name is the session name. One can change the experiment name by typing a new name in the text box beside the option.
-'''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.
+Then press button '''Finish'''. Upon successful import operation the selected traces will be stored in the '''Traces''' directory of the specified tracing project. A directory with the connection name will be created under the '''Traces''' directory. Underneath that, the session directory structure as well as the trace names will be preserved in the destination tracing project. For '''Kernel''' traces the trace type '''Linux 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.
-[[Image:images/LTTng2ImportOverwriteConfirmationDialog.png]]
+'''Note''': If a trace already exists with the same name in the destination directory, 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 kernel becomes kernel(2).
-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/LTTng2ImportOverwriteConfirmationDialog.png]]
-[[Image:images/LTTng2ImportRenameDialog.png]]
+If one selects '''Rename All''', '''Overwrite All''' or '''Skip All''' the choice will be applied for all traces with a name conflict.
=== 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.
+=== Saving Tracing Sessions ===
+Since LTTng Tools v2.5.0 it is possible to save tracing sessions. The LTTng Tools command-line tool will save the sessions to XML files located by default in a subdirectory of the user's home directory. The Trace Compass '''Control''' view integration for this feature will also store this session profile file into the user's Trace Compass workspace. This will allow user's to re-use session profiles across remote nodes. To save one or more sessions, select the tree nodes of the relevant sessions and press the right mouse button. Then select the '''Save...''' entry of the context-sensitive menu.
+
+[[Image:images/LTTng2SaveAction.png]]
+
+A new display will open for saving the sessions.
+
+[[Image:images/LTTng2SaveDialog.png]]
+
+By default the '''force''' button is selected that will overwrite any conflicting session profile files on the remote node. Click on '''Ok''' to save the session(s) otherwise click on '''Cancel'''. Upon successful operation, the session profile files will be saved on the remote node and then will be downloaded to the user's Trace Compass workspace. In the case that a session XML file already exists in the workspace the user will be prompted to skip or overwrite the existing profile file.
+
+=== Loading Tracing Sessions ===
+Since LTTng Tools v2.5.0 it is possible to load tracing sessions. The Trace Compass '''Control''' view integrations for this feature will allow to load session profiles that are located in the user's Trace Compass workspace, or alternatively, that are located on the remote node. In the first case the session profiles will be uploaded to the remote node before the load command is executed.
+
+To load one or more sessions, select the tree node '''Sessions''' and press the right mouse button. Then select the '''Load...''' entry of the context-sensitive menu.
+
+[[Image:images/LTTng2LoadAction.png]]
+
+A new display will open for loading session profiles.
+
+[[Image:images/LTTng2LoadDialog.png]]
+
+By default the '''Local''' button and '''force''' buttons are selected and session profile files of the user's workspace will be listed. Select one or more profiles, update the '''force''' button if needed and then click '''Ok'''. This will upload the session profile files to the remote node. If a session profile file with the same name already exist on the remote node, it will be overwritten. If the '''force''' button is selected any existing session with a conflicting name will be destroyed and a new one will be created.
+
+Alternatively, one can select the '''Remote''' button to list all available session profile files on the remote node. To load one of the remote session profiles, select one or more profiles, update the '''force''' button if needed and then click '''Ok'''.
+
+[[Image:images/LTTng2LoadRemoteDialog.png]]
+
+Upon successful operation, the tracing sessions of the selected session profiles are created and added under the tree node '''Sessions''' the '''Control''' view.
+
+=== Managing Tracing Session Profiles ===
+The '''LTTng Remote Profiles''' preference page is used to manage the list of LTTng session profiles that are stored in the user's Trace Compass workspace. To open the preference page, select the '''Manage...''' button of the '''Load Sessions''' dialog described in chapter [[#Loading Tracing Sessions |Loading Tracing Sessions]]. Alternatively, select '''Window -> Preferences''' from the top level menu and go to '''Tracing -> LTTng Remote Profiles'''.
+
+[[Image:images/LTTng2ManageSessionConfig.png]]
+
+The following actions can be performed from this dialog:
+
+* Delete
+
+Select one or more LTTng session profiles from the list and click the '''Delete''' button to remove the profile from the Trace Compass workspace. The user will be prompted to confirm the deletion.
+
+* Import...
+
+Click the '''Import...''' button and select a file from the opened file dialog to import a session profile file. If the file name conflicts with an existing profile file, the user will be prompted to skip or overwrite the existing profile file.
+* Export...
+
+Select one or more session profile files from the list, click the '''Export...''' button and enter or select a directory in the opened directory dialog to export the profile files. If the file name conflicts with an existing profile file in the destination directory, the user will be prompted to skip or overwrite the existing profile file.
+
== 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:
== 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.
+Several 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]]
[[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'''.
+To configure the LTTng command execution timeout, select '''Tracing -> Remote Connection Preferences''' and enter a timeout value into the text field '''Command Timeout (in seconds)'''. Then 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.
== 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.
+The '''''Control Flow''''' view is a LTTng-specific view that shows per-process events graphically. The Linux Kernel Analysis is executed the first time a LTTng Kernel is opened. After opening the trace, the element '''Control Flow''' is added under the '''Linux 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]]
[[Image:images/Cfv_global.png]]
-The view is divided into the following important sections: '''process tree and information''', '''control flow''' and the '''toolbar'''.
+The view is divided into the following important sections: '''process tree and information''', '''control flow''' and the '''toolbar'''. The time axis is aligned with other views that support automatic time axis alignment (see [[#Automatic Time Axis Alignment | Automatic Time Axis Alignment]]).
The following sections provide detailed information for each part of the Control Flow View.
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).
+It is possible to sort the columns of the tree by clicking on the column header. Subsequent clicking will change the sort order. The hierarchy, i.e. the parent-child relationship is kept. When opening a trace for the first time, the processes are sorted by '''birth time'''. The sort order and column will be preserved when switching between open traces. Note that when opening an experiment the processes will be sorted within each trace.
+
=== 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.
* '''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
+* '''Ctrl-mouse wheel up/down''': zoom in or out horizontally
+* '''Shift-Ctrl-mouse wheel up/down''': zoom in or out vertically
* '''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.
+==== Using the keyboard ====
+
+The states flow is usable with the keyboard. The following actions are set:
+*'''arrow-right key''': selects the next state for the selected process
+*'''arrow-left key''': selects the previous state for the selected process
+*'''Shift + arrow-right key''': updates the selection end time of the current selection range by selecting the next state of the current process
+*'''Shift + arrow-left key''': updates the selection end time of the current selection range by selecting the previous state of the current process
+*'''.''': selects the next active marker
+*''',''': selects the previous active marker
+*'''Shift + .''': updates the selection end time of the current selection range by selecting the next active marker boundary
+*'''Shift + ,''': updates the selection end time of the current selection range by selecting the previous active marker boundary
+*'''arrow-down''': selects the next process
+*'''arrow-up''': selects the previous process
+*'''Page Down''': selects the process down one page
+*'''Page Up''': selects the process up one page
+*'''Home''': selects the first process
+*'''End''': selects the last process
+*'''Enter''': toggles the expansion state of the current process in the tree
+*'''+''': Zoom-in horizontally
+*'''-''': Zoom-out horizontally
+*'''Ctrl + +''': Zoom-in vertically
+*'''Ctrl + -''': Zoom-out vertically
+*'''Ctrl + 0''': Reset the vertical zoom
+
+When the selection indicators are changed, 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:
=== Toolbar ===
+<!-- Keep in sync with ref:resource-view-toolbar -->
+
The Control Flow View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
{|
+| [[Image:images/link.gif]]
+| Align Views
+| Disable and enable the automatic time axis alignment of time-based views. Disabling the alignment in this view will disable this feature across all the views because it's a workspace preference.
+|-
| [[Image:images/filter_items.gif]]
| Show View Filter
-| Opens the process filter dialog
+| Opens the process filter dialog. Filter settings will be preserved when switching between open traces.
|-
| [[Image:images/show_legend.gif]]
| Show Legend
-| Displays the states legend
+| Displays the states legend.
|-
| [[Image:images/home_nav.gif]]
| Reset the Time Scale to Default
-| Resets the zoom window to the full range
+| Resets the zoom window to the full range.
|-
| [[Image:images/prev_event.gif]]
| Select Previous Event
-| Selects the previous state for the selected process
+| Selects the previous state for the selected process. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/next_event.gif]]
| Select Next Event
-| Selects the next state for the selected process
+| Selects the next state for the selected process. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
+|-
+| [[Image:images/add_bookmark.gif]]
+| Add Bookmark...
+| Adds a bookmark at the current selection range. A bookmark is a user-defined interval marker. The '''Add Bookmark''' dialog is opened where the user can enter a description and choose the highlighting color and alpha (transparency) value. This button is replaced by the '''Remove Bookmark''' button if the current selection range corresponds to an existing bookmark. The bookmarks can also be managed in the '''Bookmark View'''.
+|-
+| [[Image:images/remove_bookmark.gif]]
+| Remove Bookmark
+| Removes the bookmark at the current selection range. This button replaces the '''Add Bookmark''' when the current selection range corresponds to an existing bookmark.
+|-
+| [[Image:images/prev_bookmark.gif]]
+| Previous Marker
+| Selects the previous active marker. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
+|-
+| [[Image:images/next_bookmark.gif]]
+| Next Marker
+| Selects the next active marker. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range. Clicking the button drop-down arrow will open a menu where marker categories can be made active or inactive for navigation. To toggle the display of a marker category, use the '''View Menu''' instead.
|-
| [[Image:images/prev_menu.gif]]
| Select Previous Process
-| Selects the previous process
+| Selects the previous process.
|-
| [[Image:images/next_menu.gif]]
| Select Next Process
-| Selects the next process
+| Selects the next process.
|-
| [[Image:images/zoomin_nav.gif]]
| Zoom In
-| Zooms in on the selection by 50%
+| Zooms in on the selection by 50%.
|-
| [[Image:images/zoomout_nav.gif]]
| Zoom Out
-| Zooms out on the selection by 50%
+| Zooms out on the selection by 50%.
|-
| [[Image:images/hide_arrows.gif]]
| Hide Arrows
-| Toggles the display of arrows on or off
+| 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
+| Selects the previous state following CPU execution across processes. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/follow_arrow_fwd.gif]]
| Follow CPU Forward
-| Selects the next state following CPU execution across processes
+| Selects the next state following CPU execution across processes. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
+|}
+
+View Menu
+
+{|
+|
+| Show Markers
+| A marker highlights a time interval. A marker can be used for instance to indicate a time range where lost events occurred or to bookmark an interesting interval for future reference. Selecting a category name will toggle the visibility of markers of that category.
|}
+=== Marker Axis ===
+
+The marker axis is visible only when at least one marker category with markers for the current trace is shown.
+
+The marker axis displays one row per marker category. Each marker's time range and/or label (if applicable) are drawn on the marker axis.
+
+Clicking on any marker's time range or label will set the current time selection to the marker's time or time range.
+
+Clicking on the "X" icon to the left of the marker category name will hide this marker category from the time graph. It can be shown again using the corresponding '''Show Markers''' menu item in the view menu.
+
+The marker axis can be collapsed and expanded by clicking on the icon at the top left of the marker axis. The marker axis can be completely removed by hiding all available marker categories.
+
== 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.
+This view is specific to LTTng kernel traces. The Linux Kernel Analysis is executed the first time a LTTng Kernel is opened. After opening the trace, the element '''Resources''' is added under the '''Linux 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
+This view shows the state of system resources i.e. if changes occurred 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.
+The time axis is aligned with other views that support automatic time axis alignment (see [[#Automatic Time Axis Alignment | Automatic Time Axis Alignment]]).
+
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]]
[[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.
+Then, by selecting '''Next Event''', it will show the next state transition and the event that occurred at this time.
[[Image:images/RV_infobox2.png|Shows the next state of the IRQ]]
=== Navigation ===
-See Control Flow View's '''[[#Using_the_mouse | Using the mouse]]''' and '''[[#Zoom_region | Zoom region]]'''.
+See Control Flow View's '''[[#Using_the_mouse | Using the mouse]]''', '''[[#Using_the_keyboard | Using the keyboard]]''' and '''[[#Zoom_region | Zoom region]]'''.
=== Incomplete regions ===
=== Toolbar ===
+<!-- ref:resource-view-toolbar -->
+
The Resources View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
{|
+| [[Image:images/link.gif]]
+| Align Views
+| Disable and enable the automatic time axis alignment of time-based views. Disabling the alignment in this view will disable this feature across all the views because it's a workspace preference.
+|-
+| [[Image:images/filter_items.gif]]
+| Show View Filter
+| Opens the resources filter dialog. Filter settings will be preserved when switching between open traces.
+|-
| [[Image:images/show_legend.gif]]
| Show Legend
-| Displays the states legend
+| Displays the states legend.
|-
| [[Image:images/home_nav.gif]]
| Reset the Time Scale to Default
-| Resets the zoom window to the full range
+| Resets the zoom window to the full range.
|-
| [[Image:images/prev_event.gif]]
| Select Previous Event
-| Selects the previous state for the selected resource
+| Selects the previous state for the selected resource. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/next_event.gif]]
| Select Next Event
-| Selects the next state for the selected resource
+| Selects the next state for the selected resource. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
+|-
+| [[Image:images/add_bookmark.gif]]
+| Add Bookmark...
+| Adds a bookmark at the current selection range. A bookmark is a user-defined interval marker. The '''Add Bookmark''' dialog is opened where the user can enter a description and choose the highlighting color and alpha (transparency) value. This button is replaced by the '''Remove Bookmark''' button if the current selection range corresponds to an existing bookmark. The bookmarks can also be managed in the '''Bookmark View'''.
+|-
+| [[Image:images/remove_bookmark.gif]]
+| Remove Bookmark
+| Removes the bookmark at the current selection range. This button replaces the '''Add Bookmark''' when the current selection range corresponds to an existing bookmark.
+|-
+| [[Image:images/prev_bookmark.gif]]
+| Previous Marker
+| Selects the previous active marker. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
+|-
+| [[Image:images/next_bookmark.gif]]
+| Next Marker
+| Selects the next active marker. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range. Clicking the button drop-down arrow will open a menu where marker categories can be made active or inactive for navigation.
|-
| [[Image:images/prev_menu.gif]]
| Select Previous Resource
|-
| [[Image:images/zoomin_nav.gif]]
| Zoom In
-| Zooms in on the selection by 50%
+| Zooms in on the selection by 50%.
|-
| [[Image:images/zoomout_nav.gif]]
| Zoom Out
-| Zooms out on the selection by 50%
+| Zooms out on the selection by 50%.
|}
+View Menu
+
+{|
+|
+| Show Markers
+| A marker highlights a time interval. A marker can be used for instance to indicate a time range where lost events occurred or to bookmark an interesting interval for future reference. Selecting a category name will toggle the visibility of markers of that category.
+|}
+
+=== Marker Axis ===
+
+See Control Flow View's '''[[#Marker_Axis | Marker Axis]]'''.
+
== 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.
+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 '''Linux Kernel Analysis''' tree element of the Project Explorer.
[[Image:images/LTTng_OpenCpuUsageView.png]]
[[Image:images/LTTng_CpuUsageView.png]]
-The view is divided into the following important sections: '''Process Information''' and the '''CPU Usage Chart'''.
+The view is divided into the following important sections: '''Process Information''' and the '''CPU Usage Chart'''. The time axis is aligned with other views that support automatic time axis alignment (see [[#Automatic Time Axis Alignment | Automatic Time Axis Alignment]]).
=== Process Information ===
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
* '''Total''': The total CPU usage
-[[Image:images/LTTng_CpuUsageViewToolTip.png]]
+==== Toolbar ====
+
+The CPU Usage View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
+
+{|
+| [[Image:images/link.gif]]
+| Align Views
+| Disable and enable the automatic time axis alignment of time-based views. Disabling the alignment in the this view will disable this feature across all the views because it's a workspace preference
+|-
+|}
+[[Image:images/LTTng_CpuUsageViewToolTip.png]]
== LTTng Kernel Events Editor ==
* '''Timestamp''': the event timestamp
* '''Channel''': the event channel (data collector)
+* '''CPU''': the CPU on which the event was taken
* '''Event Type''': the event type (or kernel marker)
-* '''Content''': the raw event content
+* '''Contents''': the fields (or payload) of this event
+* '''TID''': The ID of the thread this event belongs to
+* '''Prio''': The priority of the thread this event belongs to
[[Image:images/LTTng2EventsEditor.png]]
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 '''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. Note that pressing the '''Shift''' key at the same time will update the selection end time of the current selection.
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.
** <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.
+(If you are dealing with C++ executables, you may want to use ''nm --demangle'' instead to get readable function names.)
+
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).
+=== Navigation ===
+
+See Control Flow View's '''[[#Using_the_mouse | Using the mouse]]''', '''[[#Using_the_keyboard | Using the keyboard]]''' and '''[[#Zoom_region | Zoom region]]'''.
+
+=== Marker Axis ===
+
+See Control Flow View's '''[[#Marker_Axis | Marker Axis]]'''.
+
== 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.
[[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.
+The time axis is aligned with other views that support automatic time axis alignment (see [[#Automatic Time Axis Alignment | Automatic Time Axis Alignment]]).
+
+Please note this view will not show shared memory or stack memory usage.
+
+=== Using the mouse ===
+
+The Memory Usage chart is usable with the mouse. The following actions are set:
+
+* '''left-click''': select a time or time range begin 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
+
+
+=== Toolbar ===
+
+The Memory Usage View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
+
+{|
+| [[Image:images/link.gif]]
+| Align Views
+| Disable and enable the automatic time axis alignment of time-based views. Disabling the alignment in the this view will disable this feature across all the views because it's a workspace preference
+|-
+|}
+
+[[Image:images/LTTng_CpuUsageViewToolTip.png]]
Please note this view will not show shared memory or stack memory usage.
The ones used for trace synchronization are '''inet_sock_local_in''' and '''inet_sock_local_out'''.
-== Synchronize traces in TMF ==
+== Synchronize traces in Trace Compass ==
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.
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 ==
+== Managing XML files containing analyses ==
+
+The '''Manage XML Analyses''' dialog is used to manage the list of XML files containing analysis. To open the dialog:
+
+* Open the '''Project Explorer''' view.
+* Select '''Manage XML Analyses...''' from the '''Traces''' folder context menu.
+
+[[Image:images/ManageXMLAnalysis.png]]
+
+The list of currently defined XML analyses is displayed on the left side of the dialog.
-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''.
+The following actions can be performed from this dialog:
+
+* Import
+
+Click the '''Import''' button and select a file from the opened file dialog to import an XML file containing an analysis. The file 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. If an invalid file is selected, an error message will be displayed to the user.
-[[Image:images/import_XML_analysis.png| Import XML analysis menu]]
+* Export
-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.
+Select an XML file from the list, click the '''Export''' button and enter or select a file in the opened file dialog to export the XML analysis. Note that if an existing file containing an analysis is selected, its content will be replaced with the analysis to export.
+
+* Delete
-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 .
+Select an XML file from the list and click the '''Delete''' button to remove the XML file. Deleting an XML file will close all the traces for which this analysis applies and remove the analysis.
== 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''.
+''For now, the XSD is only available through the source code in org.eclipse.tracecompass.tmf.analysis.xml.core/src/org/eclipse/tracecompass/tmf/analysis/xml/core/module/xmlDefinition.xsd''.
An empty file, with no content yet would look like this:
=== 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.
+Before we start, we'll define a few terms used in the following sections. The interested reader should read the [https://wiki.eclipse.org/index.php/Trace_Compass#User_Guides 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.
<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">
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.tracecompass.tmf.analysis.xml.core/src/org/eclipse/tracecompass/tmf/analysis/xml/core/module/xmlDefinition.xsd">
<stateProvider version="0" id="my.test.state.provider">
<head>
<traceType id="my.trace.id" />
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">
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.tracecompass.tmf.analysis.xml.core/src/org/eclipse/tracecompass/tmf/analysis/xml/core/module/xmlDefinition.xsd">
<timeGraphView id="my.test.time.graph.view">
<head>
<analysis id="my.test.state.provider" />
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:
+We will use the Linux 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/*">
<pre>
<head>
- <analysis id="org.eclipse.linuxtools.lttng2.kernel.analysis" />
+ <analysis id="org.eclipse.tracecompass.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">
+<tmfxml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../org.eclipse.tracecompass.tmf.analysis.xml.core/src/org/eclipse/tracecompass/tmf/analysis/xml/core/module/xmlDefinition.xsd">
<xyView id="my.test.xy.chart.view">
<head>
- <analysis id="org.eclipse.linuxtools.lttng2.kernel.analysis" />
+ <analysis id="org.eclipse.tracecompass.lttng2.kernel.analysis" />
<label value="CPU status XY view" />
</head>
[[Image:images/XML_xy_chart.png| XML XY chart]]
+= Latency Analyses =
+
+Trace Compass offers a feature called Latency analysis. This allows an analysis to return intervals and these intervals will be displayed in four different views. An example analysis is provided with kernel system call latencies being provided. The available views are:
+
+* System Call Latencies
+A '''table''' of the raw latencies. This view is useful to inspect individual latencies.
+
+ [[Image:images/LatenciesTable.png| Latency Table example - System Call Latencies]]
+
+
+* System Call Latency vs Time
+A time aligned '''scatter chart''' of the latencies with respect to the current window range. This view is useful to see the overall form of the latencies as they arrive.
+
+[[Image:images/LatenciesScatter.png| Latency Scatter Chart example - System Call Latency vs Time]]
+
+
+* System Call Latency Statistics
+A view of the total '''statistics''' of the latencies. These show the ''minimum'', ''maximum'', ''average'' and ''standard deviation'' of the latencies when applicable. This tool is useful for finding the outliers on a per-category basis.
+
+[[Image:images/LatenciesStatistics.png| Latency Statistics example - System Call Latency Statistics]]
+
+
+* System Call Density
+A '''density''' view, analyzing the current time range. This is useful to find global outliers.
+
+[[Image:images/LatenciesDensity.png| Latency Densities example - System Call Density]]
+
+= Virtual Machine Analysis =
+
+Virtual environments are usually composed of host machines, who each run an hypervisor program on which one or many guests can be run. Tracing a guest machine alone can often yield some strange results as from its point of view, it has full use of the resources, but in reality, most resources are shared with the host and other guests.
+
+To better understand what is happening in such an environment, it is necessary to trace all the machines involved, guests and hosts, and correlate this information in an experiment that will display a complete view of the virtualized environment.
+
+== Virtual Machine Experiment ==
+
+A trace has to be taken for each machine, guest and host, in the virtualized environment. The host trace is the most important to have, as missing guests will only give an incomplete view of the system, but missing hosts usually won't allow to identify the hypervisor, nor determine when a guest is preempted from the host CPUs. The virtual machine analysis only makes sense if the host trace is available.
+
+Once all the traces are imported in Trace Compass, they can be [[#Creating a Experiment | added to an experiment]]. The type of the experiment should by set to '''Virtual Machine Experiment''' by clicking on the right mouse button over the experiment name, then selecting '''Select Experiment Type...'''.
+
+[[Image:images/vmAnalysis/VM_experiment.png | Virtual Machine Experiment]]
+
+Depending on the hypervisor used, traces might need to be [[#Trace synchronization | synchronized]] so that they have the same time reference and their events can be correctly correlated.
+
+== Virtual CPU View ==
+
+The Virtual CPU view shows the status of CPUs and threads on guests augmented with the preemption and hypervisor data we get from the host.
+
+In the image below, we see for the virtual CPU status that it has a few more states than the CPUs in the [[#Resources View | Resources View]]: in red and purple respectively, when the virtual CPU is running hypervisor code and when the CPU is preempted on the host.
+
+The entries for each thread of the machine corresponds to the one from the [[#Control flow | Control Flow View]], augmented with the data from the Virtual CPU, so that we see that even though it is running from the guest's point of view, it is actually not running when the Virtual CPU it runs on is in preempted or hypervisor mode.
+
+[[Image:images/vmAnalysis/VM_CPU_view.png | Virtual CPU view]]
+
+== Hypervisor-specific Tracing ==
+
+In order to be able to correlate data from the guests and hosts traces, each hypervisor supported by Trace Compass requires some specific events, that are sometimes not available in the default installation of the tracer.
+
+The following sections describe how to obtain traces for each hypervisor.
+
+=== Qemu/KVM ===
+
+The Qemu/KVM hypervisor require extra tracepoints not yet shipped in LTTng for both guests and hosts, as well as compilation with the full kernel source tree on the host, to have access to kvm_entry/kvm_exit events on x86.
+
+Obtain the source code with extra tracepoints, 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.
+
+ # git checkout addons
+ # make
+ # sudo make modules_install
+ # sudo depmod -a
+
+On the host, to have complete kvm tracepoints support, the make command has to include the full kernel tree. So first, you'll need to obtain the kernel source tree. See your distribution's documentation on how to get it. This will compile extra modules, including lttng-probe-kvm-x86, which we need.
+
+ # make KERNELDIR=/path/to/kernel/dir
+
+The lttng addons modules must be inserted manually for the virtual machine extra tracepoints to be available:
+
+ # sudo modprobe lttng-addons
+ # sudo modprobe lttng-vmsync-host # on the host
+ # sudo modprobe lttng-vmsync-guest # on the guest
+
+The following tracepoints will be available
+
+ # sudo lttng list -k
+ Kernel events:
+ -------------
+ ...
+ kvm_entry (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ kvm_exit (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ vmsync_gh_guest (loglevel: TRACE_EMERG (0)) (type: tracepoint) # on the guest
+ vmsync_hg_guest (loglevel: TRACE_EMERG (0)) (type: tracepoint) # on the guest
+ vmsync_gh_host (loglevel: TRACE_EMERG (0)) (type: tracepoint) # on the host
+ vmsync_hg_host (loglevel: TRACE_EMERG (0)) (type: tracepoint) # on the host
+ ...
+
+Host and guests can now be traced together and their traces added to an experiment. Because each guest has a different clock than the host, it is necessary to synchronize the traces together. Unfortunately, automatic synchronization with the virtual machine events is not completely implemented yet, so another kind of synchronization needs to be done, with TCP packets for instance. See section on [[#Trace synchronization | trace synchronization]] for information on how to obtain synchronizable traces.
+
= 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.
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.
+Bob did note an exact second one glitch occurred: 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.
+At this point he closes FooMonitor and notices the bug disappeared. 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.
+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.
= References =
-* [http://www.eclipse.org/linuxtools/projectPages/lttng/ Linux Tools - LTTng integration]
+* [http://www.eclipse.org/tracecompass Trace Compass project]
+* [https://wiki.eclipse.org/index.php/Trace_Compass#User_Guides Trace Compass User Guides]
* [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]
projects / deliverable / tracecompass.git / blobdiff