** 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
Tracing projects have two sub-folders: '''Traces''' which holds the individual traces, and '''Experiments''' which holds sets of traces that we want to correlate.
=== Importing Traces in a Project ===
+
+==== Open Trace File, Open Trace Directory ====
+
+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).
+
+[[Image:images/OpenTraceFile.png]]
+
+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.
+
+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.
+
==== Batch Importing ====
+
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/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 previous way of importing a trace is still available. To access it, simply select '''Import...''' menu item in the context-sensitive menu.
+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]]
-[[Image:images/ProjectImportTraceAction.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.
-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/tracePackageImages/importTraceFolder.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.
+At this point, the '''Trace Package Import Wizard''' is opened.
-[[Image:images/ProjectImportTraceDialog.png]]
+[[Image:images/tracePackageImages/importPackage.png]]
-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.
+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.
-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.
+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 ===
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 two data controls:
+On the top left, there are three text controls:
+
+* '''Selection Start''': Displays the start time of the current selection
+* '''Selection End''': Displays the end time of the current selection
+* '''Window Span''': Displays the current zoom window size in seconds
+
+The controls can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly. To modify both selection times simultaneously, press the link icon [[Image:images/link.gif]] which disables the '''Selection End''' control input.
+
+The large (full) histogram, at the bottom, shows the event distribution over the whole trace or set of traces. It also has a smaller semi-transparent orange window, with a cross-hair, that shows the current zoom window.
+
+The smaller (zoom) histogram, on top right, corresponds to the current zoom window, a sub-range of the event set.
-* '''Current Event (sec)''': Displays the current time or selected time range begin time
-* '''Window Span (sec)''': Displays the current time range window size
+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.
-Both control can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly.
+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 vertical blue bar shows the currently selected time. The current time can be changed by clicking on the histogram. Shift-clicking the histogram will select a time range, in which case there will be vertical blue bars at the begin and end time and the region in between will be shaded.
+* '''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''': Sets the current time to the first 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 ==
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 ==
Custom parser wizards allow the user to define their own parsers for text or XML traces. The user defines how the input should be parsed into internal trace events and identifies the event fields that should be created and displayed. Traces created using a custom parser can be correlated with other built-in traces or traces added by plug-in extension.
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]]
[[Image:images/LTTng2ImportDialog.png]]
-By default all traces are selected. Also, 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. 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.
+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.
projects / deliverable / tracecompass.git / blobdiff