+== External Analyses ==
+
+Trace Compass supports the execution of '''external analyses''' conforming to the machine interface of [https://github.com/lttng/lttng-analyses/releases/tag/v0.4.3 LTTng-Analyses 0.4.3], or any later [https://github.com/lttng/lttng-analyses/releases LTTng-Analyses 0.4.x] version. Later (0.5+) versions of LTTng-Analyses will be supported by later versions of Trace Compass.
+
+An external analysis is a [[#Run an External Analysis|program executed by Trace Compass]]. When the program is done analyzing, Trace Compass generates a '''[[#Open a Report|report]]''' containing its results. A report contains one or more tables which can also be viewed as bar and scatter [[#Create a Chart from a Result Table|charts]].
+
+'''Note''': The program to execute is found by searching the directories listed in the standard <code>$PATH</code> environment variable when no path separator (<code>/</code> on Unix and OS X, <code>\</code> on Windows) is found in its command.
+
+Trace Compass ships with a default list of ''descriptors'' of external analyses (not the analyses themselves), including the descriptors of the [http://github.com/lttng/lttng-analyses LTTng analyses]. If the LTTng analyses project is installed, its analyses are available when opening or importing an LTTng kernel trace.
+
+=== Run an External Analysis ===
+
+To run an external analysis:
+
+# [[#Importing Traces to the Project|Import a trace to the project]].
+# Make sure the trace is opened by double-clicking its name in the [[#Project Explorer View]].
+# Under the trace in the [[#Project Explorer View]], expand ''External Analyses'' to view the list of available external analyses.<p>The external analyses which are either missing or not compatible with the trace are stroke and cannot be executed.</p><p>[[Image:images/externalAnalyses/external-analyses-list.png]]</p>
+# '''Optional''': If you want the external analysis to analyze a specific time range of the current trace, make a time range selection.<p>You can use views like the [[#Histogram View]] and the [[#Control Flow View]] (if it's available for this trace) to make a time range selection.</p><p>External analyses are executed on the current time range selection if there is one, or on the whole trace otherwise.</p>
+# Right-click the external analysis to run and click '''Run External Analysis'''.<p>[[Image:images/externalAnalyses/run-external-analysis.png]]</p>
+# In the opened ''External Analysis Parameters'' window, optionally enter extra parameters to pass to the program.<p>[[Image:images/externalAnalyses/external-analysis-parameters-dialog.png]]</p>
+# Click '''OK''' to start the analysis.
+
+Note that many external analyses can be started concurrently.
+
+When the external analysis is done analyzing, its results are saved as a [[#Open a Report|report]] in Trace Compass. The tables contained in this report are also automatically opened into a new report view when the analysis is finished.
+
+=== Open a Report ===
+
+A '''report''' is created after a successful [[#Run an External Analysis|execution of an external analysis]].
+
+To open a report:
+
+* Under ''Reports'' under a trace in the [[#Project Explorer View]], double-click the report to open.<p>Each result table generated by the external analysis is shown in its own tab in the opened report view.</p><p>[[Image:images/externalAnalyses/report-view.png]]</p>
+
+=== Create a Chart from a Result Table ===
+
+To create a bar or a scatter chart from the data of a given result table:
+
+# [[#Open a Report|Open the report]] containing the result table to use for creating the chart.
+# In the opened report view, click the tab of the result table to use for creating the chart.
+# Click the ''View Menu'' button, then click either '''New custom bar chart''' or '''New custom scatter chart'''.<p>[[Image:images/externalAnalyses/new-custom-scatter-chart-menu.png]]</p>
+# In the opened ''Bar chart series creation'' or ''Scatter chart series creation'' window, under ''Series creator'', select a column to use for the X axis of the chart, and one or more columns to use for the Y axis of the chart, then click '''Add''' to create a series.<p>[[Image:images/externalAnalyses/chart-configuration-dialog.png]]</p><p>Repeat this step to create more series.</p>
+# Click '''OK''' to create the chart.<p>The chart is created and shown at the right of its source result table.</p><p>[[Image:images/externalAnalyses/table-and-chart.png]]</p>
+
+=== Show or Hide a Result Table ===
+
+To show or hide a result table once a [[#Create a Chart from a Result Table|chart]] has been created:
+
+* In the report view, click the ''Toggle the Table view of the results'' button.<p>[[Image:images/externalAnalyses/table-and-chart-toggle-button.png]]</p><p>If the result table was visible, it is now hidden:</p><p>[[Image:images/externalAnalyses/chart-only.png]]</p>
+
+=== Add and Remove a User-Defined External Analysis ===
+
+You can add a user-defined external analysis to the current list of external analyses. Note that the command to invoke must conform to the machine interface of [http://github.com/lttng/lttng-analyses LTTng analyses] 0.4.
+
+'''Note''': If you want to create your own external analysis, consider following the [http://lttng.org/files/lami/lami-1.0.1.html LAMI 1.0 specification], which is supported by later versions of Trace Compass.
+
+To add a user-defined external analysis:
+
+# Under any trace in the [[#Project Explorer View]], right-click ''External Analyses'' and click '''Add External Analysis'''.<p>[[Image:images/externalAnalyses/add-external-analysis.png]]</p>
+# In the opened ''Add External Analysis'' window, enter the name of the new external analysis and the associated command to run.<p>[[Image:images/externalAnalyses/add-external-analysis-dialog.png]]</p><p>The name is the title of the external analysis as shown under ''External Analyses'' in the [[#Project Explorer View]].</p><p>The command is the complete command line to execute. You can put arguments containing spaces or other special characters in double quotes.</p><p>'''Note''': If the command is not a file system path, then it must be found in the directories listed in the <code>$PATH</code> environment variable.</p>
+# Click '''OK''' to add the user-defined external analysis.<p>A user-defined external analysis with a green icon is created under ''External Analyses'' in the [[#Project Explorer View]].</p><p>[[Image:images/externalAnalyses/user-defined-external-analysis.png]]</p>
+
+'''Note''': The new external analysis entry is saved in the workspace.
+
+To remove a user-defined external analysis:
+
+* Under ''External Analyses'' in the [[#Project Explorer View]], right-click the external analysis to remove and click '''Remove External Analysis'''.<p>[[Image:images/externalAnalyses/remove-external-analysis.png]]</p><p>'''Note''': Only user-defined (green icon) external analyses can be removed.</p>
+