Searching and filtering of events in the table can be performed by entering matching conditions in one or multiple columns in the header row (the first row below the column header).
-To apply a matching condition to a specific column, click on the column's header row cell, type in a [http://download.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html regular expression]. You can also enter a simple text string and it will be automatically be replaced with a 'contains' regular expression.
+To apply a matching condition to a specific column, click on the column's header row cell, type in a [http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html regular expression]. You can also enter a simple text string and it will be automatically be replaced with a 'contains' regular expression.
Press the '''Enter''' key to apply the condition as a search condition. It will be added to any existing search conditions.
== Statistics View ==
-The Statistics View displays the various event counters that are collected when analyzing a trace. The data is organized per trace. After opening a trace, the element '''Statistics''' is added under the '''Tmf Statistics Analysis''' tree element in the Project Explorer. To open the view, double-click the '''Statistics''' tree element. Alternatively, select '''Statistics''' under '''Tracing''' within the '''Show View''' window ('''Window''' -> '''Show View''' -> '''Other...'''). This view shows 3 columns: ''Level'' ''Events total'' and ''Events in selected time range''. After parsing a trace the view will display the number of events per event type in the second column and in the third, the currently selected time range's event type distribution is shown. The cells where the number of events are printed also contain a colored bar with a number that indicates the percentage of the event count in relation to the total number of events. The statistics is collected for the whole trace. This view is part of the '''Tracing and Monitoring Framework (TMF)''' and is generic. It will work for any trace type extensions. For the LTTng 2.0 integration the Statistics view will display statistics as shown below.:
+The Statistics View displays the various event counters that are collected when analyzing a trace. After opening a trace, the element '''Statistics''' is added under the '''Tmf Statistics Analysis''' tree element in the Project Explorer. To open the view, double-click the '''Statistics''' tree element. Alternatively, select '''Statistics''' under '''Tracing''' within the '''Show View''' window ('''Window''' -> '''Show View''' -> '''Other...'''). The statistics is collected for the whole trace. This view is part of the '''Tracing and Monitoring Framework (TMF)''' and is generic. It will work for any trace type extensions.
-[[Image:images/LTTng2StatisticsView.png]]
+The view is separated in two sides. The left side of the view presents the Statistics in a table. The table shows 3 columns: ''Level'' ''Events total'' and ''Events in selected time range''. The data is organized per trace. After parsing a trace the view will display the number of events per event type in the second column and in the third, the currently selected time range's event type distribution is shown. The cells where the number of events are printed also contain a colored bar with a number that indicates the percentage of the event count in relation to the total number of events.
+
+[[Image:images/LTTng2StatisticsTableView.png]]
+
+The right side illustrates the proportion of types of events into two pie charts. The legend of each pie chart gives the representation of each color in the chart.
+* The ''Global'' pie chart displays the general proportion of the events in the trace.
+* When there is a range selection, the ''Events in selection'' pie chart appears next to the ''Global'' pie chart and displays the proportion the event in the selected range of the trace.
+
+[[Image:images/LTTng2StatisticsPieChartView.png]]
By default, the statistics use a state system, therefore will load very quickly once the state system is written to the disk as a supplementary file.
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.
+== External Analyses ==
+
+Trace Compass supports the execution of '''external analyses''' conforming to the machine interface of [http://github.com/lttng/lttng-analyses LTTng analyses] 0.4. Later versions of LTTng analyses are 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>
+
== 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.
* '''Category:''' Enter a category name for the trace type.
* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser.
* '''Time Stamp format:''' Enter the date and time pattern that will be used to output the Time Stamp.<br>
-Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/tracecompass/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
+Note: information about date and time patterns can be found here: [http://archive.eclipse.org/tracecompass/doc/stable/org.eclipse.tracecompass.doc.user/reference/api/org/eclipse/tracecompass/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
Click the '''Add next line''', '''Add child line''' or '''Remove line''' buttons to create a new line of input or delete it. For each line of input, enter the following information:
* '''Regular expression:''' Enter a regular expression that should match the input line in the log, using capturing groups to extract the data.<br>
-Note: information about date and time patterns can be found here: [http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html]
+Note: information about regular expression patterns can be found here: [http://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html]
* '''Cardinality:''' Enter the minimum and maximum number of lines matching this line's regular expression that must be found in the log. At least the minimum number of lines must be found before the parser will consider the next line. Child lines will always be considered first.
* '''Category:''' Enter a category name for the trace type.
* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser.
* '''Time Stamp format:''' Enter the date and time pattern that will be used to output the Time Stamp.<br>
-
-Note: information about date and time patterns can be found here: [../reference/api/org/eclipse/tracecompass/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
+Note: information about date and time patterns can be found here: [http://archive.eclipse.org/tracecompass/doc/stable/org.eclipse.tracecompass.doc.user/reference/api/org/eclipse/tracecompass/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
Click the '''Add document element''' button to create a new document element and enter a name for the root-level document element of the XML file.
By default the domain '''Kernel''' is selected and the kernel specific data sections are created. From this dialog box kernel '''Tracepoint''' events, '''System calls (Syscall)''', a '''Dynamic Probe''' or a '''Dynamic Function entry/return''' probe can be enabled. Note that events of one of these types at a time can be enabled.
+To enable all '''Tracepoints''' and all '''System calls (Syscall)''', select the button '''Select''' of section '''All Tracepoint Events and Syscalls''' and press '''Ok'''.
+
+[[Image:images/LTTng2EnableAllEventsDialog.png]]
+
+Upon successful operation, the domain '''Kernel''' will be created in the tree (if neccessary), the default channel with name "channel0" will be added under the domain (if necessary) as well as all a wildcard event '''*''' of type '''TRACEPOINT''' under the channel and a wildcard event '''*''' of type '''SYSCALL''' . The channel and events will be '''ENABLED'''.
+
To enable '''Tracepoint''' events, first select the corresponding '''Select''' button, then select either all tracepoins (select '''All''') or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press '''Ok'''.
[[Image:images/LTTng2TracepointEventsDialog.png]]
|
| Show Markers
| A marker highlights a time interval. A marker can be used for instance to indicate a time range where lost events occurred or to bookmark an interesting interval for future reference. Selecting a category name will toggle the visibility of markers of that category.
+|-
+|
+| Thread Presentation
+| Select the threads layout. Two layouts are available. '''Flat''' layout lists the threads in a flat list per trace. '''Hierarchical''' layout shows the threads in a parent-child tree per trace.
|}
=== Marker Axis ===
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.
+=== Follow CPU ===
+It is possible to follow a CPU by right-clicking on its entry in the view, then selecting ''Follow CPU X'' where X is the number of the CPU. Following a CPU will filter the [[#LTTng CPU Usage View | CPU Usage View]] to display only usage for the selected CPU. To unfollow a CPU, one needs to right-click on any CPU entry and select ''Unfollow CPU''.
+
=== Navigation ===
See Control Flow View's '''[[#Using_the_mouse | Using the mouse]]''', '''[[#Using_the_keyboard | Using the keyboard]]''' and '''[[#Zoom_region | Zoom region]]'''.
[[Image:images/LTTng_CpuUsageViewToolTip.png]]
+==== CPU Filtering ====
+[[#Follow CPU | Follow a CPU]] will filter the CPU Usage View and will display only usage for the followed CPU.
== Kernel Memory Usage ==
[[Image:images/waitAnalysis/KernelWaitAnalysisDjango.png]]
+== Input/Output Analysis ==
+
+TraceCompass can analyse disk input/output through the read/write system calls to get the read/write per processes, but also with the disk request events, to get the actual reads and writes to disk.
+
+=== Get the trace ===
+
+The following tracepoints should be enabled to get the disk read/write data. Also, enabling syscalls will allow to match the reads and writes per processes.
+
+ # sudo lttng list -k
+ Kernel events:
+ -------------
+ ...
+ block_rq_complete (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ block_rq_insert (loglevel: TRACE_EMERG (0)) (type: tracepoint)
+ block_rq_issue (loglevel: TRACE_EMERG (0)) (type: tracepoint) # on the guest
+ block_bio_frontmerge (loglevel: TRACE_EMERG (0)) (type: tracepoint) # on the guest
+ ...
+
+For full disk request tracking, some extra tracepoints are necessary. They are not required for the I/O analysis, but make the analysis more complete. Here is the procedure to get those tracepoints that are not yet part of the mainline kernel.
+
+ # git clone https://github.com/giraldeau/lttng-modules.git
+ # cd lttng-modules
+
+Checkout the addons branch, compile and install lttng-modules as per the lttng-modules documentation.
+
+ # git checkout addons
+ # make
+ # sudo make modules_install
+ # sudo depmod -a
+
+The lttng addons modules must be inserted manually for the extra tracepoints to be available:
+
+ # sudo modprobe lttng-addons
+ # sudo modprobe lttng-elv
+
+And enable the following tracepoint
+
+ addons_elv_merge_requests
+
+=== Input/Output Views ===
+
+The following views are available for input/output analyses:
+
+* Disk I/O Activity
+A time aligned XY chart of the read and write speed for the different disks on the system. This view is useful to see where there was more activity on the disks and whether it was mostly reads or writes.
+
+ [[Image:images/io/diskIoActivity.png| Disk I/O Activity Example]]
== LTTng Kernel Events Editor ==
Trace Compass offers a feature called Latency analysis. This allows an analysis to return intervals and these intervals will be displayed in four different views. An example analysis is provided with kernel system call latencies being provided. The available views are:
-* System Call Latencies
+* System Call Latencies
A '''table''' of the raw latencies. This view is useful to inspect individual latencies.
[[Image:images/LatenciesTable.png| Latency Table example - System Call Latencies]]
* System Call Latency Statistics
-A view of the total '''statistics''' of the latencies. These show the ''minimum'', ''maximum'', ''average'' and ''standard deviation'' of the latencies when applicable. This tool is useful for finding the outliers on a per-category basis.
+A view of the total '''statistics''' of the latencies. These show the ''minimum'', ''maximum'', ''average'', ''standard deviation'', and ''count'' of the latencies when applicable. This tool is useful for finding the outliers on a per-category basis.
+
+Right-clicking on an entry of the table and select '''Go to minimum''' allows to select the range of the minimum latency for the selected entry and synchronize the other views to this time range.
+
+Right-clicking on an entry of the table and select '''Go to maximum''' allows to select the range of the maximum latency for the selected entry and synchronize the other views to this time range.
[[Image:images/LatenciesStatistics.png| Latency Statistics example - System Call Latency Statistics]]
projects / deliverable / tracecompass.git / blobdiff