** 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]]
-==== Importing ====
-
-The previous way of importing a trace is still available. To access it, simply select '''Import...''' menu item in the context-sensitive menu.
-
-[[Image:images/ProjectImportTraceAction.png]]
-
-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'''.
-
-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.
-
-[[Image:images/ProjectImportTraceDialog.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.
-
-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.
-
=== 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.
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.
projects / deliverable / tracecompass.git / blobdiff