For more information about LTTng, refer to the project [http://lttng.org site]
-'''Note''': This User Guide covers the integration of the latest LTTng (v2.0) in Eclipse. The legacy version (v0.x) of both the tracer and the LTTng integration are no longer being maintained but are still available for download. The User Guide for the legacy LTTng integration is available [http://wiki.eclipse.org/index.php/Linux_Tools_Project/LTTng/User_Guide here].
+'''Note''': This User Guide covers the integration of the latest LTTng (v2.0) in Eclipse. The legacy version (v0.x) of both the tracer and the LTTng integration are no longer being maintained.
== About Tracing ==
* 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 event
+* Views synchronization of currently selected time or time range, and window time range
* Efficient searching and filtering of events
* Support for trace bookmarks
** Right-click in the Project view and select "New Project"
** Enter the name of your project (e.g. "MyLTTngProject")
** The project will be created. It will contain 2 empty folders: "Traces" and "Experiments"
-* Import a sample trace
-** Right-click on the newly created project "Traces" folder and select "Import..."
+* Open a sample trace
+** Right-click on the newly created project "Traces" folder and select "Open Trace Directory..."
** Navigate to the sample LTTng trace that you want to visualize
-** Select that trace (check box), select the trace type (e.g. CTF: Kernel Trace), and press "Finish"
** The newly imported trace should appear under the Traces folder
* Visualize the trace
** Expand the Traces folder
* [[#Filters_View | Filters View]]
* [[#Time_Chart_View | Time Chart View]]
* [[#Environment_Variables_View | Environment Variables View]]
+* [[#State_System_Explorer_View | State System Explorer View]]
+* [[#Call_Stack_View | Call Stack View]]
The framework also supports user creation of [[#Custom_Parsers | Custom Parsers]].
=== Importing Traces in a Project ===
-The '''Traces''' folder holds the set of traces available for experiments. To import a trace to the traces folder, select the Traces folder and click the right mouse button. Then select '''Import...''' menu item in the context-sensitive menu.
+==== Open Trace File, Open Trace Directory ====
-[[Image:images/ProjectImportTraceAction.png]]
+To open a single trace, right-click on the Traces folder and select '''Open Trace File...''' (for logs and such) or '''Open Trace directory...''' (for CTF traces).
-A new display 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 by entering the path directly in the '''Source Directory''' or by browsing the file system (click on button browse). Then select the traces to import in the list of files and folders. Optionally, select the '''Trace Type''' from the drop-down menu, select or deselect the checkboxes for '''Overwrite existing trace without warning''' and '''Create links into workspace'''. When all options are configured, click on '''Finish'''.
+[[Image:images/OpenTraceFile.png]]
-Note, that traces of certain types (e.g. LTTng Kernel) are actually a composite of multiple channel traces grouped under a folder. It is the folder that has to be imported.
+Select the file or directory, and the trace will be imported into the selected Traces folder. It will attempt to auto-detect the trace type. If the trace validates as more than one trace type, a window will prompt the user to select a trace type. Once a trace type is selected, the trace will load.
-[[Image:images/ProjectImportTraceDialog.png]]
+Note that a trace type is an extension point of the '''Tracing and Monitoring Framework (TMF)'''. Depending on the which features are loaded, the list of available trace types can vary.
-Upon successful importing the traces will be stored in the '''Traces''' folder. If a trace type was selected in the import dialog, then the corresponding icon will be displayed. If no trace type is selected the unknown icon [[Image:images/unknown_parser.gif]] will be displayed. Linked traces will have a little arrow as decorator on the right bottom corner.
+==== Batch Importing ====
-Note that trace type is an extension point of the '''Tracing and Monitoring Framework (TMF)'''. Depending on the which features are loaded, the list of trace types can vary.
+The '''Batch Import Trace Wizard''' allows users to search their media for traces and import multiple traces of varying trace types simultaneously. It also handles name clashes and renaming of traces.
+
+The '''Traces''' folder holds the set of traces available for a tracing project. To import a set of traces to the '''Traces''' folder, one can open the '''Import...''' menu from the '''File''' main menu.
+
+[[Image:images/importImages/importImportMenu.png]]
+
+Then select '''Batch Trace Import'''
+
+[[Image:images/importImages/importMenuSelect.png]]
+
+Or one can select the '''Traces''' folder by double clicking on the project name.
+
+[[Image:images/importImages/importSelectTracingProject.png]]
+
+Then click the right mouse button on the '''Traces''' folder. Then select '''Batch Import...''' menu item in the context-sensitive menu.
+
+[[Image:images/importImages/importBatchImport.png]]
+
+At this point, the '''Batch import wizard''' is opened.
+
+The '''Available trace types''' page is visible. Select a trace type to scan for by clicking an item in trace types tree. If one selects a parent element, the new state will be propagated to the children.
+
+[[Image:images/importImages/importSelectTraceTypeToImport.png]]
+
+When that is done, the warning message will go away and the user can click '''Next >'''.
+
+[[Image:images/importImages/importSelectTraceTypeComplete.png]]
+
+Then select one or more files or directories to scan for traces. The directories added will be recursively scanned, all children files and directories will be scanned. This can be slow depending on the size of the directory to scan.
+
+[[Image:images/importImages/importSelectFilesToScan.png]]
+
+One can add a directory by clicking on '''Add Directory...''' then selecting a directory to import.
+
+[[Image:images/importImages/importSelectedDirectory.png]]
+
+One can also add a file by clicking on '''Add File...''' then selecting a file to import.
+
+[[Image:images/importImages/importAddFile.png]]
+
+Once the files and directories are selected, a background scanner will already start scanning them for potential matches. to select the candidates, click '''Next >'''.
+
+Here the user will see the results of the scan. The list will grow as more files are scanned.
+To select a trace to import, first open a trace type.
+
+[[Image:images/importImages/importScan1.png]]
+
+Then select the trace to import.
+
+[[Image:images/importImages/importScan2.png]]
+
+When that is done, typically one can press '''Finish''', and the trace will be imported. They can set the trace to be '''linked''' or '''copied'''. A '''linked''' trace is not copied to the user's workspace, rather, the original file is used. This is useful for traces that are very large and that the user does not want to copy several times. '''Copied''' traces are as their name indicates, copied to the local workspace. This is useful if there is a trace on a network or on some removable media. The user can also specify if the trace should '''overwrite''' the resources in the workspace or not.
+
+[[Image:images/importImages/importScan3.png]]
+
+One can select several traces also and import them simultaneously. In this case there is a problem, the name of both traces are the same, this is a conflicting name and needs to be resolved.
+
+[[Image:images/importImages/importScan4.png]]
+
+To do so, select one of the conflicting traces, then '''click on its name'''. Then type in a new name.
+
+[[Image:images/importImages/importScan5.png]]
+
+Here the traces shall be copied instead of linked.
+
+[[Image:images/importImages/importScan6.png]]
+
+At this point, press '''Finish''' to import the traces.
+
+If the '''Finish''' button is grayed, or if the user wishes to import to a different project, they need to press '''Next >'''. The user then needs to select a project to import to on the '''options''' page.
+
+[[Image:images/importImages/importOptions.png]]
+
+You will then see the traces in the '''Traces''' folder as shown below and can '''open''' them by '''double-clicking''' on them. For more details on how to open a trace see section [[#Opening_a_Trace_or_Experiment|Opening a Trace or Experiment]].
+
+[[Image:images/importImages/importFinish.png]]
+
+=== Trace Package Exporting and Importing ===
+
+A trace package is an archive file that contains the trace itself and can also contain its bookmarks and its supplementary files. Including supplementary files in the package can improve performance of opening an imported trace but at the expense of package size.
+
+==== Exporting ====
+
+The '''Export Trace Package Wizard''' allows users to select a trace and export its files and bookmarks to an archive on a media.
+
+The '''Traces''' folder holds the set of traces available for a tracing project. To export a trace contained in the '''Traces''' folder, one can open the '''Export...''' menu from the '''File''' main menu. Then select '''Trace Package Export'''
+
+[[Image:images/tracePackageImages/fileExport.png]]
+
+At this point, the '''Trace Package Export''' is opened. The project containing the trace has to be selected first then the trace to be exported.
+
+[[Image:images/tracePackageImages/chooseTrace.png]]
+
+One can also open the wizard and skip the first page by selecting a trace in the '''Traces''' folder by double clicking on the project name, double clicking on the '''Traces''' folder, right-clicking on the trace then selecting '''Export Trace Package...''' menu item in the context-sensitive menu.
+
+[[Image:images/tracePackageImages/exportSelectedTrace.png]]
+
+Next, the user can choose the content to export and various format options for the resulting file.
+
+[[Image:images/tracePackageImages/exportPackage.png]]
+
+The '''Trace''' item is always selected and represents the files that constitute the trace. The '''Supplementary files''' items represent files that are typically generated when a trace is opened by the viewer. Sharing these files can speed up opening a trace dramatically but also increases the size of the exported archive file. The ''Size'' column can help to decide whether or not to include these files. Lastly, by selecting '''Bookmarks''', the user can export all the bookmarks so that they can be shared along with the trace.
+
+The '''To archive file''' field is used to specify the location where to save the resulting archive.
+
+The '''Options''' section allows the user to choose between a tar archive or a zip archive. Compression can also be toggled on or off.
+
+When Finish button is clicked, the package is generated and saved to the media.
+
+==== Importing ====
+
+The '''Import Trace Package Wizard''' allows users to select a previously exported trace package from their media and import the content of the package in the workspace.
+
+The '''Traces''' folder holds the set of traces for a tracing project. To import a trace package to the '''Traces''' folder, one can open the '''Import...''' menu from the '''File''' main menu. Then select '''Trace Package Import'''.
+
+[[Image:images/tracePackageImages/fileImport.png]]
+
+One can also open the wizard by double clicking on the project name, right-clicking on the '''Traces''' folder then selecting '''Import Trace Package...''' menu item in the context-sensitive menu.
+
+[[Image:images/tracePackageImages/importTraceFolder.png]]
+
+At this point, the '''Trace Package Import Wizard''' is opened.
+
+[[Image:images/tracePackageImages/importPackage.png]]
+
+The '''From archive file''' field is used to specify the location of the trace package to export. The user can choose the content to import in the tree.
+
+If the wizard was opened using the File menu, the destination project has to be selected in the '''Into project''' field.
+
+When Finish is clicked, the trace is imported under the project's Trace folder.
=== Selecting a Trace Type ===
It is also possible to drop a trace, resource, file or folder into an existing experiment. If the item does not already exist as a trace in the project's trace folder, it will first be copied or imported, then the trace will be added to the experiment.
+=== Link with Editor ===
+
+The tracing projects support the feature '''Link With Editor''' of the Project Explorer view. With this feature it is now possible to<br/>
+* select a trace element in the Project Explorer view and the corresponding [[#Events_Editor | Events Editor]] will get focus if the relevant trace is open.
+* select an [[#Events_Editor | Events Editor]] and the corresponding trace element will be highlighted in the Project Explorer view.
+
+To enable or disable this feature toggle the '''Link With Editor''' button of the Project Explorer view as shown below.
+
+[[Image:images/TMF_LinkWithEditor.png]]
+
== Events Editor ==
The Events editor shows the basic trace data elements (events) in a tabular format. The editors can be dragged in the editor area so that several traces may be shown side by side. These traces are synchronized by timestamp.
The highlighted event is the ''current event'' and is synchronized with the other views. If you select another event, the other views will be updated accordingly. The properties view will display a more detailed view of the selected event.
+An event range can be selected by holding the '''Shift''' key while clicking another event or using any of the cursor keys ('''Up'''', '''Down''', '''PageUp''', '''PageDown''', '''Home''', '''End'''). The first and last events in the selection will be used to determine the current selected time range for synchronization with the other views.
+
[[Image:images/LTTng2EventProperties.png]]
The Events editor can be closed, disposing a trace. When this is done, all the views displaying the information will be updated with the trace data of the next event editor tab. If all the editor tabs are closed, then the views will display their empty states.
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.
-==== Callsite ====
+==== Source Code ====
-If a callsite is available in the trace for the selected event, the item '''Open Callsite''' is shown in the context menu. Selecting this menu item will attempt to find the callsite source file in all opened projects in the workspace. If multiple candidates exist, a selection dialog will be shown to the user. The selected source file will be opened in its default language editor. If no candidate is found, an error dialog is shown displaying the callsite information.
+If a source file is available in the trace for the selected event, the item '''Open Source Code''' is shown in the context menu. Selecting this menu item will attempt to find the source file in all opened projects in the workspace. If multiple candidates exist, a selection dialog will be shown to the user. The selected source file will be opened, at the correct line, in its default language editor. If no candidate is found, an error dialog is shown displaying the source code information.
==== EMF Model ====
If an EMF model URI is available in the trace for the selected event, the item '''Open Model Element''' is shown in the context menu. Selecting this menu item will attempt to open the model file in the project specified in the URI. The model file will be opened in its default model editor. If the model file is not found, an error dialog is shown displaying the URI information.
+=== Exporting To Text ===
+It is possible to export the content of the trace to a text file based on the columns displayed in the events table. If a filter (see '''[[#Filtering| Filtering]]''') was defined prior exporting only events that match the filter will be exported to the file. To export the trace to text, press the right mouse button on the events table. A context-sensitive menu will show. Select the '''Export To Text...''' menu option. A file locater dialog will open. Fill in the file name and location and then press on '''OK'''. A window with a progress bar will open till the export is finished.
+
+''Note'': The columns in the text file are separated by tabs.
+
== Histogram View ==
The Histogram View displays the trace events distribution with respect to time. When streaming a trace, this view is dynamically updated as the events are received.
-
[[Image:images/HistogramView.png]]
+The '''Hide Lost Events''' toggle button [[Image:images/hide_lost_events.gif]] in the local toolbar allows to hide the bars of lost events. When the button is selected it can be toggled again to show the lost events.
+
+On the top left, there are three text controls:
+
+* '''Selection Start''': Displays the start time of the current selection
+* '''Selection End''': Displays the end time of the current selection
+* '''Window Span''': Displays the current zoom window size in seconds
+
+The controls can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly. To modify both selection times simultaneously, press the link icon [[Image:images/link.gif]] which disables the '''Selection End''' control input.
-On the top left, there are two data controls:
+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.
-* '''Current Event (sec)''': Displays the timestamp of the currently selected event
-* '''Window Span (sec)''': Displays the current time range window size
+The smaller (zoom) histogram, on top right, corresponds to the current zoom window, a sub-range of the event set.
-Both control can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly.
+The x-axis of each histogram corresponds to the event timestamps. The start time and end time of the histogram range is displayed. The y-axis shows the maximum number of events in the corresponding histogram bars.
+The vertical blue line(s) show the current selection time (or range). If applicable, the region in the selection range will be shaded.
-The large histogram, at the bottom, shows the event distribution over the whole trace or set of traces. It also has a smaller semi-transparent window, with a cross-hair, that shows the currently selected time range window. The time range window can be zoomed in/out by using the mouse wheel. It can also be selected by the mouse and dragged to another region of the trace.
+The mouse can be used to control the histogram:
-The smaller histogram, on top right, corresponds to the currently selected time range window, a sub-range of the event set. Its size can also be zoomed in/out using the mouse wheel.
+* '''Left-click''': Set a selection time
+* '''Left-drag''': Set a selection range
+* '''Shift-left-click or drag''': Extend or shrink the selection range
-The x-axis of each histogram corresponds to the events timestamps. The timestamp of the first and the last event of the respective ranges is displayed. The y-axis of each histogram shows the minimum/maximum number of events in the corresponding histogram bars.
+* '''Middle-click or Ctrl-left-click''': Center the zoom window on mouse (full histogram only)
+* '''Middle-drag or Ctrl-left-drag''': Move the zoom window
-The dashed vertical magenta bar, on the right, shows the position of the last event. The dashed vertical red bar shows the relative position of the currently selected event. The current event can be changed by clicking on the histogram.
+* '''Right-drag''': Set the zoom window
+* '''Shift-right-click or drag''': Extend or shrink the zoom window (full histogram only)
-Hovering the mouse over an histogram bar pops up an information window that displays the start/end time of the corresponding bar as well as the number of events it represents.
+* '''Mouse wheel up''': Zoom in
+* '''Mouse wheel down''': Zoom out
+
+Hovering the mouse over an histogram bar pops up an information window that displays the start/end time of the corresponding bar, as well as the number of events (and lost events) it represents. If the mouse is over the selection range, the selection span in seconds is displayed.
In each histogram, the following keys are handled:
-* '''Left''': Moves the current event to the previous non-empty bar
-* '''Right''': Moves the current event to the next non-empty bar
-* '''Home''': Displays the current event to the first histogram bar
-* '''End''': Displays the current event to the last non-empty histogram bar
+* '''Left Arrow''': Moves the current event to the previous non-empty bar
+* '''Right Arrow''': Moves the current event to the next non-empty bar
+* '''Home''': Sets the current time to the first non-empty bar
+* '''End''': Sets the current time to the last non-empty histogram bar
== Statistics View ==
The filters can be more complex than what can be achieved with the filter header row in the events table. The filter is defined in a tree node structure, where the node types can be any of '''EVENTTYPE''', '''AND''', '''OR''', '''CONTAINS''', '''EQUALS''', '''MATCHES''' or '''COMPARE'''. Some nodes types have restrictions on their possible children in the tree.
-The '''EVENTTYPE''' node filters against the event type of the trace as defined in a plugin 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 '''EVENTTYPE''' node filters against the event type of the trace as defined in a plug-in extension or in a custom parsers. When used, any child node will have its field combo box restricted to the possible fields of that event type.
The '''AND''' node applies the logical ''and'' condition on all of its children. All children conditions must be true for the filter to match. A ''not'' operator can be applied to invert the condition.
When a filter is applied in the events table, the non-matching ticks are removed from the Time Chart view.
-The Time Chart only supports traces that are opened in an editor. The use of an editor is specified in the plugin extension for that trace type, or is enabled by default for custom traces.
+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.
== Environment Variables View ==
A new feature of CTF traces is their ability to store user defined data that is not to be placed in an event. It is generally data that is per-trace specific, such as the tracer version and the trace domain. It will be populated when a trace is loaded if the trace has environment variables. <br>
[[Image:images/LTTng2EnvironmentsView.png]]<br>
-The above picture shows a trace loaded that was collevcted with the '''lttng-modules''' version '''2'''.'''0'''.'''0''' tracer. It is a '''kernel''' trace of the '''3.2.0-18-generic''' '''linux''' kernel.
+The above picture shows a trace loaded that was collected with the '''lttng-modules''' version '''2'''.'''0'''.'''0''' tracer. It is a '''kernel''' trace of the '''3.2.0-18-generic''' '''linux''' kernel.
+
+== State System Explorer View ==
+
+The State System Explorer view allows the user to inspect the state interval values of every attribute of a state system at a particular time.
+
+The view shows a tree of currently selected traces and their registered state system IDs. For each state system the tree structure of attributes is displayed. The attribute name, quark, value, start and end time, and full attribute path are shown for each attribute.
+
+To modify the time of attributes shown in the view, select a different current time in other views that support time synchronization (e.g. event table, histogram view). When a time range is selected, this view uses the begin time.
+
+== Call Stack View ==
+
+The Call Stack view allows the user to visualize the call stack per thread over time, if the application and trace provide this information.
+
+The view shows the call stack information for the currently selected trace.
+
+The table on the left-hand side of the view shows the threads and call stack. The function name, depth, entry and exit time and duration are shown for the call stack at the selected time.
+
+Double-clicking on a function entry in the table will zoom the time graph to the selected function's range of execution.
+
+The time graph on the right-hand side of the view shows the call stack state graphically over time. The function name is visible on each call stack event if size permits. The color of each call stack event is randomly assigned based on the function name, allowing for easy identification of repeated calls to the same function.
+
+Clicking on the time graph will set the current time and consequently update the table with the current call stack information.
+
+Shift-clicking on the time graph will select a time range. When the selection is a time range, the begin time is used to update the stack information.
+
+Double-clicking on a call stack event will zoom the time graph to the selected function's range of execution.
+
+Clicking the '''Select Next Event''' or '''Select Previous Event''' or using the left and right arrows will navigate to the next or previous call stack event, and select the function currently at the top of the call stack.
+
+Clicking the '''Import Mapping File''' ([[Image:images/import.gif]]) icon will open a file selection dialog, allowing you to import a text file containing mappings from function addresses to function names. If the callstack provider for the current trace type only provides function addresses, a mapping file will be required to get the function names in the view. See the following sections for an example with LTTng-UST traces.
+
+=== Using the Callstack View with LTTng-UST traces ===
+
+There is support in the LTTng-UST integration plugin to display the callstack of applications traced with the ''liblttng-ust-cyg-profile.so'' library (see the ''liblttng-ust-cyg-profile'' man page for additional information). To do so, you need to:
+
+* Recompile your application with "''-g -finstrument-functions''".
+* Add the ''vtid'' and ''procname'' contexts to your trace session. See the [[#Adding Contexts to Channels and Events of a Domain | Adding Contexts to Channels and Events of a Domain]] section. Or if using the command-line:
+** <pre>lttng add-context -u -t vtid -t procname</pre>
+* Preload the ''liblttng-ust-cyg-profile'' library when running your program:
+** <pre>LD_PRELOAD=/usr/lib/liblttng-ust-cyg-profile.so ./myprogram</pre>
+
+Once you load the resulting trace, making sure it's set to the ''Common Trace Format - LTTng UST Trace'' type, the Callstack View should be populated with the relevant information. However, since GCC's cyg-profile instrumentation only provides function addresses, and not names, an additional step is required to get the function names showing in the view. The following section explains how to do so.
+
+=== Importing a function name mapping file for LTTng-UST traces ===
+
+If you followed the steps in the previous section, you should have a Callstack View populated with function entries and exits. However, the view will display the function addresses instead of names in the intervals, which are not very useful by themselves. To get the actual function names, you need to:
+
+* Generate a mapping file from the binary, using:
+** <pre>nm myprogram > mapping.txt</pre>
+* Click the '''Import Mapping File''' ([[Image:images/import.gif]]) button in the Callstack View, and select the ''mapping.txt'' file that was just created.
+
+The view should now update to display the function names instead. Make sure the binary used for taking the trace is the one used for this step too (otherwise, there is a good chance of the addresses not being the same).
== Custom Parsers ==
By default only the first matching entry will be highlighted. To highlight all matching entries in the preview input data, click the '''Highlight All''' button. This might take a few seconds to process, depending on the input size.
-Click the '''Next''' button to go to the second page of the wizard.
+Click the '''Next >''' button to go to the second page of the wizard.
[[Image:images/CustomTextParserOutput.png]]
The '''Preview:''' text field of each capturing element and attribute and of the Time Stamp will be filled from the parsed data of the first matching log entry. Also, when creating a new child element or attribute, its element or attribute name will be suggested if possible from the preview input data.
-Click the '''Next''' button to go to the second page of the wizard.
+Click the '''Next >''' button to go to the second page of the wizard.
[[Image:images/CustomXMLParserOutput.png]]
[[Image:images/LTTng2SelectConnection.png]]
-To enter the host information manually select first the button '''Edit connection information'''. Then the text fields '''Connection Name''' and '''Host Name''' will enabled. Enter the relevant information and then select '''Ok'''.
+To enter the host information manually select first the button '''Edit connection information'''. Then the text fields '''Connection Name''', '''Host Name''' and '''Port Number''' will be enabled. The '''Host Name''' holds the IP address or DNS name of the remote system. The '''Connection Name''' is the alias name to be displayed in the Control View. The '''Port Number''' is the port number to be used for the IP connection. This parameter is optional and if it is omitted the default port will be used. Enter the relevant information and then select '''Ok'''.
[[Image:images/LTTng2EditConnection.png]]
A new display will show for providing the user name and password. This display only opens if no password had been saved before. Enter user name and password in the '''Enter Password''' dialog box and select '''Ok'''.
-The '''Host Name''' holds the IP address or DNS name of the remote system.
-The '''Connection Name''' is the alias name to be displayed in the Control View.
-
[[Image:images/LTTng2EnterPassword.png]]
After pressing '''Ok''' the SSH connection will be established and after successful login the Control View implementation retrieves the LTTng Tracer Control information. This information will be displayed in the Control View in form of a tree structure.
Fill in the '''Session Name''' and optionally the '''Session Path''' and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
+==== Creating a Tracing Session With Advanced Options ====
+LTTng Tools version v2.1.0 introduces the possibility to configure the trace output location at session creation time. The trace can be stored in the (tracer) local file system or can be transferred over the network.
+
+To create a tracing session and configure the trace output, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]]. A dialog box will open for entering information about the session to be created.
+
+[[Image:images/LTTng2CreateSessionDialog_Advanced.png]]
+
+The button '''Advanced >>>''' will only show if the remote host has LTTng Tools v2.1.0 installed. To configure the trace output select the '''Advanced >>>''' button. The Dialog box will be shown new fields to configure the trace output location.
+
+[[Image:images/LTTng2CreateSessionDialog_TracePath.png]]
+
+By default, the button '''Use same protocol and address for data and control''' is selected which allows to configure the same '''Protocol''' and '''Address''' for both data URL and control URL.
+
+If button '''Use same protocol and address for data and control''' is selected the '''Protocol''' can be '''net''' for the default network protocol which is TCP (IPv4), '''net6''' for the default network protocol which is TCP (IPv6) and '''file''' for the local file system. For '''net''' and '''net6''' the port can be configured. Enter a value in '''Port''' for data and control URL or keep them empty for the default port to be used. Using '''file''' as protocol no port can be configured and the text fields are disabled.
+
+If button '''Use same protocol and address for data and control''' is not selected the '''Protocol''' can be '''net''' for the default network protocol which is TCP (IPv4), '''net6''' for the default network protocol which is TCP (IPv6), '''tcp''' for the network protocol TCP (IPv4) and '''tcp6''' for the network protocol TCP (IPv6). Note that for '''net''' and '''net6''' always the default port is used and hence the port text fields are disabled. To configure non-default ports use '''tcp''' or '''tcp6'''.
+
+The text field '''Trace Path''' allows for specifying the path relative to the location defined by the '''relayd''' or relative to the location specified by the '''Address''' when using protocol '''file'''. For more information about the '''relayd''' see '''LTTng relayd User Manual''' in chapter [[#References | References]].
+
+To create a session with advanced options, fill in the relevant parameters and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
+
+==== Creating a Snapshot Tracing Session ====
+LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After starting tracing the trace events are not stored on disk or over the network. They are only transfered to disk or over the network when the user records a snapshot. To create such a snapshot session, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]].
+
+[[Image:images/LTTng2CreateSessionDialog_Snapshot.png]]
+
+Fill in all necessary information, select checkbox for '''Snapshot Mode''' and press '''Ok'''. By default, the location for the snapshot output will be on the host where the host is located.
+
+Refer to chapter [[#Recording a Snapshot | Recording a Snapshot]] for how to create a snapshot.
+
==== Enabling Channels - General ====
Enabling channels can be done using a session tree node when the domain hasn't be created in the session or, alternatively on a domain tree node of a session in case the domain is already available.
[[Image:images/LTTng2CreateChannelDialog.png]]
-By default the domain '''Kernel''' is selected and the corresponding default values are shown. To create a UST channel, select '''UST''' under the domain section. To get the default values of UST, then press button '''Default'''.
+By default the domain '''Kernel''' is selected. To create a UST channel, select '''UST''' under the domain section. The label <Default> in any text box indicates that the default value of the tracer will be configured. To initialize the dialog box press button '''Default'''.
If required update the following channel information and then press '''Ok'''.
* '''Channel Name''': The name of the channel.
-* '''Number of Sub Buffers''': The number of sub-buffers of the channel.
-* '''Overwrite Mode''': The channel overwrite mode ('''true''' or '''false''')
-* '''Read Timer Interval''': The read timer interval.
* '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
+* '''Number of Sub Buffers''': The number of sub-buffers of the channel.
* '''Switch Timer Interval''': The switch timer interval.
+* '''Read Timer Interval''': The read timer interval.
+* '''Discard Mode''': '''Overwrite''' events in buffer or '''Discard''' new events when buffer is full.
Upon successful operation, the requested domain will be created under the session tree node as well as the requested channel will be added under the domain. The channel will be '''ENABLED'''.
+==== Configuring Trace File Rotation ====
+
+Since LTTng Tools v2.2.0 it is possible to set the maximum size of trace files and the maximum number of them. These options are located in the same dialog box that is used for enabling channels.
+
+[[Image:images/LTTng2CreateChannelDialogFileRotation.png]]
+
+* '''Maximum size of trace files''': The maximum size of trace files
+* '''Maximum number of trace files''': The maximum number of trace files
+
+==== Configuring per UID and per PID Buffers (UST only) ====
+
+Since LTTng Tools v2.2.0 it is possible to configure the type of buffers for '''UST''' application. It is now possible to choose between per '''UID''' buffers (per user ID) and per '''PID''' buffers (per process ID) using the dialog box for enabling channels.
+
+[[Image:images/LTTng2CreateChannelDialogPerUIDBuffers.png]]
+
+* '''Per PID buffers''': To activate the per PID buffers option for UST channels
+* '''Per UID buffers''': To activate the per UID buffers option for UST channels
+
+If no buffer type is selected then the default value of the tracer will be configured.
+
+Note that '''Global shared buffers''' is only for kernel channel and is pre-selected when '''Kernel''' is selected in the dalog box.
+
+==== Configuring Periodical Flush for metadata Channel ====
+
+Since LTTng Tools v2.2.0 it is possible to configure periodical flush for the metadata channel. To set this, use the checkbox '''Configure metadata channel''' then fill the switch timer interval.
+
+[[Image:images/LTTng2CreateChannelDialogMetadataFlush.png]]
+
==== Enabling Channels On Domain Level ====
Once a domain is available, channels can be enabled directly using the domain. To enable a channel under an existing domain, select the tree node of the relevant domain and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
[[Image:images/LTTng2CreateChannelOnDomainAction.png]]
-The dialog box for enabling channel will open for entering information about the channel to be created. Note that the domain is pre-selected and cannot be changed.
-
-[[Image:images/LTTng2CreateChannelOnDomainDialog.png]]
-
-Fill the relevant information and press '''Ok'''.
+The dialog box for enabling channel will open for entering information about the channel to be created. Note that the domain is pre-selected and cannot be changed. Fill the relevant information and press '''Ok'''.
==== Enabling and Disabling Channels ====
[[Image:images/LTTng2AssignedEvents.png]]
+==== Configuring Filter Expression On UST Event Fields ====
+
+Since LTTng Tools v2.1.0 it is possible to configure a filter expression on UST event fields. To configure a filter expression on UST event fields, open the enable event dialog as described in chapters [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]], [[#Enabling Events On Domain Level | Enabling Events On Domain Level]] or [[#Enabling Events On Channel Level | Enabling Events On Channel Level]], select UST if needed, select the relevant '''Tracepoint''' event(s) and enter the filter expression in the '''Filter Expression''' text field.
+
+[[Image:images/LTTng2EnableEventWithFilter.png]]
+
+Alternatively, open the dialog box for assigning events to a session and channel described in [[#Enabling Tracepoint Events From Provider | Enabling Tracepoint Events From Provider]] (for UST providers) and enter the filter expression in the '''Filter Expression''' text field.
+
+[[Image:images/LTTng2AssignEventDialogWithFilter.png]]
+
+For the syntax of the filter expression refer to the '''LTTng Tracer Control Command Line Tool User Manual''' of chapter [[#References |References]].
+
==== Adding Contexts to Channels and Events of a Domain ====
It is possible to add contexts to channels and events. Adding contexts on channels and events from the domain level, will enable the specified contexts to all channels of the domain and all their events. To add contexts on the domain level, select a domain, click right mouse button on a domain tree node (e.g. provider '''Kernel''') and select the menu item '''Add Context...''' from the context-sensitive menu.
A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter [[#Adding Contexts to Channels and Events of a Domain | Adding Contexts to Channels and Events of a Domain]]. Upon successful operation, the selected context will be added to all channels and their events of the selected domain. '''Note''' that the LTTng 2.0 tracer control on the remote host doesn't provide a way to retrieve added contexts. Hence it's not possible to display the context information in the GUI.
-==== Adding Contexts to a Event of a Specific Channel ====
+==== Adding Contexts to an Event of a Specific Channel ====
-Adding contexts to a event of a channel, select an event of a channel, click right mouse button on the corresponding event tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
+Adding contexts to an event of a channel is only available in LTTng Tools versions v2.0.0-2.1.x. The menu option won't be visible for LTTng Tools version v2.2.0 or later. To add contexts on an event select an event of a channel, click right mouse button on the corresponding event tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
[[Image:images/LTTng2AddContextToEventsAction.png]]
Upon successful operation, the tracing session will be '''ACTIVE''' and the icon of the session will be updated.
+==== Recording a Snapshot ====
+
+LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After creating a snapshot session (see [[#Creating a Snapshot Tracing Session | Creating a Snapshot Tracing Session]]) and starting tracing (see [[#Start Tracing | Start Tracing]]) it possible to record snapshots. To record a snapshot select one or more sessions and press the '''Record Snapshot''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Recored Snapshot''' menu item.
+
+[[Image:images/LTTng2RecordSnapshotAction.png]]
+
+This action can be executed many times. It is possible to import the recorded snpshots to a tracing project. The trace session might be '''ACTIVE''' or '''INACTIVE''' for that. Refer to section [[#Importing Session Traces to a Tracing Project | Importing Session Traces to a Tracing Project]] on how to import a trace to a tracing project.
+
==== Stop Tracing ====
-To stop tracing, select one or more sessions to stop in the Control View and press the '''Stop''' button. Alternatively, click the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Stop''' menu item.
+To stop tracing, select one or more sessions to stop in the Control View and press the '''Stop''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Stop''' menu item.
[[Image:images/LTTng2StopTracingAction.png]]
[[Image:images/LTTng2ImportDialog.png]]
-Select the trace to be imported by selecting the relevant traces in the tree viewer, select a tracing project from the '''Available Projects''' combo box and select the Overwrite button ('''Overwrite existing trace without warning''') if required. Then press button '''Ok'''. Upon successful import operation the the selected traces will be stored in the '''Traces''' directory of the specified tracing project. 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. 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. For '''Kernel''' traces the trace type '''LTTng Kernel''' and for '''UST''' traces the trace type '''Generic CTF Trace''' will be set. From the '''Project Explorer''' view, the trace can be analyzed further.
+
+'''Note''': The trace will be imported with a name constructed with information about session, whether it is a kernel or ust trace, ust buffer type (per UID or per PID) and snapshot details.
'''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 project, then a new confirmation dialog box will open.
[[Image:images/LTTng2ImportRenameDialog.png]]
+==== Importing Network Traces to a Tracing Project ====
+
+Since LTTng Tools v2.1.0 it is possible to store traces over the network. To import network traces, execute the '''Import''' action as described in chapter [[#Importing Session Traces to a Tracing Project|Importing Session Traces to a Tracing Project]]. For network traces the '''Batch Import Trace Wizard''' will be displayed. Follow the instructions in chapter [[#Batch Importing|Batch Importing]] to import the network traces of the current session.
+
=== Properties View ===
The Control View provides property information of selected tree component. Depending on the selected tree component different properties are displayed in the property view. For example, when selecting the node level the property view will be filled as followed:
* '''Event''' Properties (Provider)
** '''Event Name''': The name of the event.
** '''Event Type''': The event type ('''TRACEPOINT''' only).
+** '''Fields''': Shows a list of fields defined for the selected event. (UST only, since support for LTTng Tools v2.1.0)
** '''Log Level''': The log level of the event.
* '''Session''' Properties
** '''Session Name''': The name of the Session.
-** '''Session Path''': The path on the remote host where the traces will be stored.
+** '''Session Path''': The path on the remote host where the traces will be stored. (Not shown for snapshot sessions).
** '''State''': The state of the session ('''ACTIVE''' or '''INACTIVE''')
+** '''Snapshot ID''': The snapshot ID. (Only shown for snapshot sessions).
+** '''Snapshot Name''': The name of the snapshot output configuration. (Only shown for snapshot sessions).
+** '''Snapshot Path''': The path where the snapshot session is located. (Only shown for snapshot sessions).
* '''Domain''' Properties
** '''Domain Name''': The name of the domain.
+** '''Buffer Type''': The buffer type of the domain.
* '''Channel''' Properties
** '''Channel Name''': The name of the channel.
** '''Number of Sub Buffers''': The number of sub-buffers of the channel.
** '''Switch Timer Interval''': The switch timer interval.
* '''Event''' Properties (Channel)
** '''Event Name''': The name of the event.
-** '''Event Type''': The event type ('''TRACEPOINT''', '''SYSCALL''' or '''PROBE''')..
+** '''Event Type''': The event type ('''TRACEPOINT''', '''SYSCALL''' or '''PROBE''').
** '''Log Level''': The log level of the event.
** '''State''': The Event state ('''ENABLED''' or '''DISABLED''')
+** '''Filter''': Shows '''with filter''' if a filter expression is configured else property '''Filter''' is omitted. (since support for LTTng Tools v2.1.0)
=== LTTng Tracer Control Preferences ===
-Serveral LTTng 2.0 tracer control preferences exists which can be configured. To configure these preferences, select '''Window->Preferences''' from the top level menu. The preference display will open. Then select '''Tracing->LTTng Tracer Control Preferences'''. This preferences page allows the user to specify the tracing group of the user and allows the user to configure the logging of LTTng 2.0 tracer control commands and results to a file.
+Serveral LTTng 2.0 tracer control preferences exists which can be configured. To configure these preferences, select '''Window->Preferences''' from the top level menu. The preference display will open. Then select '''Tracing->LTTng Tracer Control Preferences'''. This preferences page allows the user to specify the tracing group of the user and to specify the command execution timeout as well as it allows the user to configure the logging of LTTng 2.0 tracer control commands and results to a file.
[[Image:images/LTTng2Preferences.png]]
-To change the tracing group of the user which will be specified on each command line, enter the new group name in the '''Tracing Group''' text field and click ok. The default tracing group is '''tracing''' and can be restored by pressing the '''Restore Defaults''' button.
+To change the tracing group of the user which will be specified on each command line, enter the new group name in the '''Tracing Group''' text field and click button '''OK'''. The default tracing group is '''tracing''' and can be restored by pressing the '''Restore Defaults''' button.
[[Image:images/LTTng2PreferencesGroup.png]]
-To configure logging of trace control commands and the corresponding command result to a file, selected the button '''Logging'''. To append to an existing log file, select the '''Append''' button. Deselect the '''Append''' button to overwrite any existing log file. It's possible to specify a verbose level. There are 3 levels with inceasing verbosity from '''Level 1''' to '''Level 3'''. To change the verbosity level, select the relevant level or select '''None'''. If '''None''' is selected only commands and command results are logged. Then press on button '''Ok'''. The log file will be stored in the users home directory with the name ''lttng_tracer_control.log''. The name and location cannot be changed. To reset to default preferences, click on the button '''Restore Defaults'''.
+To configure logging of trace control commands and the corresponding command result to a file, selected the button '''Logging'''. To append to an existing log file, select the '''Append''' button. Deselect the '''Append''' button to overwrite any existing log file. It's possible to specify a verbose level. There are 3 levels with inceasing verbosity from '''Level 1''' to '''Level 3'''. To change the verbosity level, select the relevant level or select '''None'''. If '''None''' is selected only commands and command results are logged. Then press on button '''OK'''. The log file will be stored in the users home directory with the name ''lttng_tracer_control.log''. The name and location cannot be changed. To reset to default preferences, click on the button '''Restore Defaults'''.
[[Image:images/LTTng2PreferencesLogging.png]]
+To configure the LTTng command execution timeout, enter a timeout value into the text field '''Command Timeout (in seconds)''' and press on button '''OK'''. To reset to the default value of 15 seconds, click on the button '''Restore Defaults'''.
+
+[[Image:images/LTTng2PreferencesTimeout.png]]
+
= LTTng Kernel Analysis =
Historically, LTTng was developped to trace the Linux kernel and, over time, a number of kernel-oriented analysis views were developped and organized in a perspective.
== Control Flow View ==
-The '''''Control Flow View''''' is a LTTng-specific view that shows per-process events graphically. To enable it, select ''Control Flow'' under ''LTTng'' within the ''Show View'' window ('''Window''' -> '''Show View''' -> '''Other...'''):
+The '''''Control Flow''''' view is a LTTng-specific view that shows per-process events graphically. To enable it, select ''Control Flow'' under ''LTTng'' within the ''Show View'' window ('''Window''' -> '''Show View''' -> '''Other...'''):
[[Image:images/Cfv_show_view.png]]
[[Image:images/Cfv_global.png]]
-The view is divided into the following important sections: '''<span style="color: #C84545;">process tree</span>''', '''<span style="color: #A1C81A;">process TID, PTID and birth time</span>''', '''<span style="color: #67A3DC;">states flow</span>''' and the '''<span style="color: #AD77D7;">toolbar</span>'''.
+The view is divided into the following important sections: '''process tree and information''', '''control flow''' and the '''toolbar'''.
The following sections provide detailed information for each part of the Control Flow View.
-=== Process tree and informations ===
+=== Process tree and information ===
Processes are organized as a tree within this view. This way, child and parent processes are easy to identify.
The layout is based on the states computed from the trace events.
-A given process may be shown at different places within the tree since the nodes are '''unique (TID, birth time) couples'''. This means that if process B of parent A dies, you'll still see it in the tree. If process A forks process B again, it will be shown as a different node since it won't have the same birth time (and probably not the same TID). This has the advantage that the tree, once loaded, never changes: horizontal scrolling within the [[#States flow|states flow]] remains possible.
+A given process may be shown at different places within the tree since the nodes are '''unique (TID, birth time) couples'''. This means that if process B of parent A dies, you'll still see it in the tree. If process A forks process B again, it will be shown as a different node since it won't have the same birth time (and probably not the same TID). This has the advantage that the tree, once loaded, never changes: horizontal scrolling within the [[#Control flow|control flow]] remains possible.
The TID column shows the process node's '''thread ID''' and the PTID column shows its '''parent thread ID''' (nothing is shown if the process has no parent).
-=== States flow ===
+=== Control flow ===
This part of the Control Flow View is probably the most interesting one. Using the mouse, you can navigate through the trace (go left, right) and zoom on a specific region to inspect its details.
-The colored bars you see represent '''states''' for the associated process node. When a process state changes in time, so does the color. States colors legend is available through a [[#Toolbar|toolbar button]]:
+The colored bars you see represent '''states''' for the associated process node. When a process state changes in time, so does the color. For state '''SYSCALL''' the name of the system call is displayed in the state bar. States colors legend is available through a [[#Toolbar|toolbar button]]:
[[Image:images/Cfv_legend.png]]
This dark yellow is what you'll see most of the time since scheduling puts processes on hold while others run.
-The vertical blue line is the '''current time indicator'''.
+The vertical blue line with T1 above it is the '''current selection indicator'''. When a time range is selected, the region between the begin and end time of the selection will be shaded and two lines with T1 and T2 above will be displayed. The time stamps corresponding to T1, T2 and their delta are shown in the status line when the mouse is hovering over the control flow.
+
+Arrows can be displayed that follow the execution of each CPU across processes. The arrows indicate when the scheduler switches from one process to another for a given CPU. The CPU being followed is indicated on the state tooltip. When the scheduler switches to and from the idle process, the arrow skips to the next process which executes on the CPU after the idle process. Note that an appropriate zoom level is required for all arrows to be displayed.
+
+The display of arrows is optional and can be toggled using the '''Hide Arrows''' toolbar button. It is also possible to follow a CPU's execution across state changes and the scheduler's process switching using the '''Follow CPU Forward/Backward''' toolbar buttons.
==== Using the mouse ====
The states flow is usable with the mouse. The following actions are set:
-* '''drag horizontally''': pan left or right
+* '''left-click''': select a time or time range begin time
+* '''Shift-left-click''': select a time range end time
+* '''left-drag horizontally''': select a time range or change the time range begin or end time
+* '''middle-drag or Ctrl-left-drag horizontally''': pan left or right
+* '''right-drag horizontally''': [[#Zoom region|zoom region]]
* '''click on a colored bar''': the associated process node is selected and the current time indicator is moved where the click happened
* '''mouse wheel up/down''': zoom in or out
-* '''drag the time ruler horizontally''': zoom in or out
-* '''drag the time ruler horizontally with the right button''': [[#Zoom region|zoom region]]
-* '''double-click the time ruler''': reset zoom
+* '''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.
==== Zoom region ====
-To zoom in on a specific region, '''right-click and drag the time ruler''' in order to draw a time range:
+To zoom in on a specific region, '''right-click and drag''' in order to draw a time range:
[[Image:images/Cfv_zoom_region.png]]
* the process name
* the pointed state name
+* the CPU (if applicable)
+* the system call name (if applicable)
* the pointed state date and start/stop times
* the pointed state duration (seconds)
The Control Flow View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
-[[Image:images/Cfv_toolbar.png]]
-
-The '''Previous event''' and '''Next event''' buttons update the current time indicator so that it's on the previous or next event.
-
-The '''Previous process''' and '''Next process''' buttons select the previous and next process node within the process tree.
+{|
+| [[Image:images/filter_items.gif]]
+| Show View Filter
+| Opens the process filter dialog
+|-
+| [[Image:images/show_legend.gif]]
+| Show Legend
+| Displays the states legend
+|-
+| [[Image:images/home_nav.gif]]
+| Reset the Time Scale to Default
+| Resets the zoom window to the full range
+|-
+| [[Image:images/prev_event.gif]]
+| Select Previous Event
+| Selects the previous state for the selected process
+|-
+| [[Image:images/next_event.gif]]
+| Select Next Event
+| Selects the next state for the selected process
+|-
+| [[Image:images/prev_menu.gif]]
+| Select Previous Process
+| Selects the previous process
+|-
+| [[Image:images/next_menu.gif]]
+| Select Next Process
+| Selects the next process
+|-
+| [[Image:images/zoomin_nav.gif]]
+| Zoom In
+| Zooms in on the selection by 50%
+|-
+| [[Image:images/zoomout_nav.gif]]
+| Zoom Out
+| Zooms out on the selection by 50%
+|-
+| [[Image:images/hide_arrows.gif]]
+| Hide Arrows
+| Toggles the display of arrows on or off
+|-
+| [[Image:images/follow_arrow_bwd.gif]]
+| Follow CPU Backward
+| Selects the previous state following CPU execution across processes
+|-
+| [[Image:images/follow_arrow_fwd.gif]]
+| Follow CPU Forward
+| Selects the next state following CPU execution across processes
+|}
== Resources View ==
+
This view is specific to kernel trace. To open it, 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]]
+[[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.
+This view shows the state of system resources i.e. if changes occured during the trace either on '''CPUs''', '''IRQs''' or '''soft IRQs''', it will appear in this view. The left side of the view present a list of resources that are affected by at least one event of the trace. The right side illustrate the state in which each resource is at some point in time. For state '''USERMODE''' it also prints the process name in the state bar. For state '''SYSCALL''' the name of the system call is
+displayed in the state region.
Just like other views, according to which trace points and system calls are activated, the content of this view may change from one trace to another.
[[Image:images/RV_infobox2.png|Shows the next state of the IRQ]]
-This view is also synchronized with the others : [[#Histogram_View | histogram]], [[#LTTng_Kernel_Events_Editor | Events editor]], [[#Control_Flow_View | control flow view]], etc.
+This view is also synchronized with the others : [[#Histogram_View | Histogram View]], [[#LTTng_Kernel_Events_Editor | Events Editor]], [[#Control_Flow_View | Control Flow View]], etc.
=== Navigation ===
=== Toolbar ===
-See Control Flow View's '''[[#Toolbar|Toolbar]]'''.
+The Resources View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
+
+{|
+| [[Image:images/show_legend.gif]]
+| Show Legend
+| Displays the states legend
+|-
+| [[Image:images/home_nav.gif]]
+| Reset the Time Scale to Default
+| Resets the zoom window to the full range
+|-
+| [[Image:images/prev_event.gif]]
+| Select Previous Event
+| Selects the previous state for the selected resource
+|-
+| [[Image:images/next_event.gif]]
+| Select Next Event
+| Selects the next state for the selected resource
+|-
+| [[Image:images/prev_menu.gif]]
+| Select Previous Resource
+| Selects the previous resource
+|-
+| [[Image:images/next_menu.gif]]
+| Select Next Resource
+| Selects the next resource
+|-
+| [[Image:images/zoomin_nav.gif]]
+| Zoom In
+| Zooms in on the selection by 50%
+|-
+| [[Image:images/zoomout_nav.gif]]
+| Zoom Out
+| Zooms out on the selection by 50%
+|}
== LTTng Kernel Events Editor ==
[[Image:images/LTTng2EventsEditor.png]]
+= Trace synchronization =
+
+It is possible to synchronize traces from different machines so that they have the same time reference. Events from the reference trace will have the same timestamps as usual, but the events from traces synchronized with the first one will have their timestamps transformed according to the formula obtained after synchronization.
+
+== Obtain synchronizable traces ==
+
+To synchronize traces from different machines, they need to exchange packets through the network and have events enabled such that the data can be matched from one trace to the other. For now, only TCP packets can be matched between two traces.
+
+LTTng traces that can be synchronized are obtained using one of two methods (both methods are compatible):
+
+=== LTTng-module network tracepoint with complete data ===
+
+The tracepoints '''net_dev_queue''' and '''netif_receive_skb''' will be used for synchronization. Both tracepoints are available in lttng-modules since version 2.2, but they do not contain sufficient data to be used to synchronize traces.
+
+An experimental branch introduces this extra data: lttng-modules will need to be compiled by hand.
+
+Obtain the source code for the experimental lttng-modules
+
+ # git clone git://git.dorsal.polymtl.ca/~gbastien/lttng-modules.git
+ # cd lttng-modules
+
+Checkout the ''net_data_experimental'' branch, compile and install lttng-modules as per the lttng-modules documentation
+
+ # git checkout net_data_experimental
+ # make
+ # sudo make modules_install
+ # sudo depmod -a
+
+This experimental branch adds IP, IPv6 and TCP header data to the tracepoints. Packets received and sent with other protocols do not have this extra header data, but all packets are captured.
+
+=== LTTng-modules addons kernel module with dynamic tracepoints ===
+
+This method adds dynamic instrumentation on TCP packets via extra kernel modules. Only TCP packets are captured.
+
+Obtain the source code, along with lttng-modules
+
+ # git clone https://github.com/giraldeau/lttng-modules.git
+ # cd lttng-modules
+
+Checkout the addons branch, compile and install lttng-modules as per the lttng-modules documentation. The ''make'' command will fail at first with a message about the unset SYSMAP variable. Instructions on how to generate a System.map are mentioned in the error message.
+
+ # git checkout addons
+ # make
+ # (follow the instructions to obtain the System.map file and set the SYSMAP variable)
+ # make
+ # sudo make modules_install
+ # sudo depmod -a
+
+The lttng-addons modules must be inserted manually for the TCP tracepoints to be made available.
+
+ # sudo modprobe lttng-addons
+ # sudo modprobe lttng-probe-addons
+
+The following tracepoints will be available
+
+ # sudo lttng list -k
+ Kernel events:
+ -------------
+ ...
+ inet_sock_create (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_delete (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_clone (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_accept (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_connect (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_local_in (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ inet_sock_local_out (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ ...
+
+The ones used for trace synchronization are '''inet_sock_local_in''' and '''inet_sock_local_out'''.
+
+== Synchronize traces in TMF ==
+
+In order to synchronize traces, create a new experiment and select all traces that need to be synchronized. Right-click on the experiment and select '''Synchronize traces'''. For each trace whose time needs to be transformed, a new trace named as the original but followed by a '_' will be created with the transformed timestamps, and the original trace will be replaced in the experiment. The original trace can still be accessed under the '''Traces''' folder.
+
+[[Image:images/Sync_menu.png| Right-click synchronize traces to perform the trace synchronization]]
+
+When opening the experiment now, all the views will be synchronized. The following screenshot presents the differences in the filtered Control Flow View before and after the time synchronization.
+
+[[Image:images/Sync_cfv.png| Example of Control Flow View before and after trace synchronization]]
+
+Information on the quality of the synchronization, the timestamp transformation formula and some synchronization statistics can be visualized in the '''Synchronization''' view. To open the '''Synchronization''' view, use the Eclipse Show View dialog ('''Window''' -> '''Show View''' -> '''Other...'''). Then select '''Synchronization''' under '''Tracing'''.
+
+[[Image:images/Sync_view.png| Example of Synchronization view]]
+
= Timestamp formatting =
Most views that show timestamps are displayed in the same time format. The unified timestamp format can be changed in the Preferences page. To get to that page, click on '''Window''' -> '''Preferences''' -> '''Tracing''' -> '''Time Format'''. Then a window will show the time format preferences.
* '''Current Format''' a format string generated by the page
* '''Sample Display''' an example of a timestamp formatted with the '''Current Format''' string.
+* '''Time Zone''' the time zone to use when displaying the time. The value '''Local time''' corresponds to the local, system-configured, time zone.
* '''Data and Time format''' how to format the date (days/months/years) and the time (hours/minutes/seconds)
* '''Sub-second format''' how much precision is shown for the sub-second units
* '''Date delimiter''' the character used to delimit the date units such as months and years
= Limitations =
* When parsing text traces, the timestamps are assumed to be in the local time zone. This means that when combining it to CTF binary traces, there could be offsets by a few hours depending on where the traces were taken and where they were read.
+* LTTng Tools v2.1.0 introduced the command line options ''--no-consumer'' and ''--disable-consumer'' for session creation as well as the commands ''enable-consumer'' and ''disable-consumer''. The LTTng Tracer Control in Eclipse doesn't support these options and commands because they will obsolete in LTTng Tools v2.2.0 and because the procedure for session creation offers already all relevant advanced parameters.
= How to use LTTng to diagnose problems =
* [http://www.eclipse.org/linuxtools/projectPages/lttng/ Linux Tools - LTTng integration]
* [http://www.lttng.org/ LTTng project]
-* [http://lttng.org/files/doc/man-pages/man1/lttng.1.html LTTng 2.0 Tracer Control Command Line Tool]
+* [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 =
projects / deliverable / tracecompass.git / blobdiff