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.
''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.
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 '''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 aspect combo box restricted to the possible aspects of that trace 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 ''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 '''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 '''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 '''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 '''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 '''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.
For numerical comparisons, strings prefixed by "0x", "0X" or "#" are treated as hexadecimal numbers and strings prefixed by "0" are treated as octal numbers.
[[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 '''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.
+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.
-
-[[Image:images/LTTng2ImportOverwriteConfirmationDialog.png]]
+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.
-To Overwrite select the '''Overwrite''' Button and press '''Ok'''.
+'''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).
-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:
[[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.
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
==== 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.
+*'''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
*'''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.
=== 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 the this view will disable this feature across all the views because it's a workspace preference
+| 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
| Select Next Event
| 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 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 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.
=== 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 the this view will disable this feature across all the views because it's a workspace preference
+| 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
| Select Next Event
| 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
| Selects the 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 '''Linux Kernel Analysis''' tree element of the Project Explorer.
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.
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]]
-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 list of currently defined XML analyses is displayed on the left side of the dialog.
-[[Image:images/import_XML_analysis.png| Import XML analysis menu]]
+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.
-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.
+* Export
-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.tracecompass.tmf.analysis.xml.core/xml_files .
+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
+
+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 ==
[[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.
projects / deliverable / tracecompass.git / blobdiff