== 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.
+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]].
Fill out the first wizard page with the following information:
* '''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.
+* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser. This will also be the default event type name.
* '''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: [http://archive.eclipse.org/tracecompass/doc/stable/org.eclipse.tracecompass.doc.user/reference/api/org/eclipse/tracecompass/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
* '''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.
+* '''Event type:''' Optionally enable this text field to enter an event type name that will override the default (trace type) when this line matches.
+
<u>Important note:</u> The custom parsers identify a log entry when the first line's regular expression matches (Root Line n). Each subsequent text line in the log is attempted to be matched against the regular expression of the parser's input lines in the order that they are defined (Line n.*). Only the first matching input line will be used to process the captured data to be stored in the log entry. When a text line matches a Root Line's regular expression, a new log entry is started.
Click the '''Add group''' or '''Remove group''' buttons to define the data extracted from the capturing groups in the line's regular expression. For each group, enter the following information:
* '''Name combo:''' Select a name for the extracted data:
-** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Timestamp''': Select this option to identify the timestamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Event type''': Select this option to identify the event type name. This will override the default or line-specific event type name.
** '''Message''': Select this option to identify the main log entry's message. This is usually a group which could have text of greater length.
** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box.
Fill out the first wizard page with the following information:
* '''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.
+* '''Trace type:''' Enter a name for the trace type, which is also the name of the custom parser. This will also be the default event type name.
* '''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: [http://archive.eclipse.org/tracecompass/doc/stable/org.eclipse.tracecompass.doc.user/reference/api/org/eclipse/tracecompass/tmf/core/timestamp/TmfTimestampFormat.html TmfTimestampFormat]
* '''Log entry:''' Select this checkbox to identify an element which represents a log entry. Each element with this name in the XML file will be parsed to a new log entry. At least one log entry element must be identified in the XML document. Log entry elements cannot be nested.
* '''Name combo:''' Select a name for the extracted data:
** '''Ignore''': Select this option to ignore the extracted element's data at this level. It is still possible to extract data from this element's child elements.
-** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Event type''': Select this option to identify the event type name. This will override the default or element-specific event type name.
+** '''Timestamp''': Select this option to identify the timestamp data. The input's data and time pattern must be entered in the format: text box.
** '''Message''': Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box. It does not have to match the element name.
* '''Action combo:''' Select the action to be performed on the extracted data:
** '''Set''': Select this option to overwrite the data for the chosen name when there is a match for this element.
** '''Append''': Select this option to append to the data with the chosen name, if any, when there is a match for this element.
** '''Append with |''' : Select this option to append to the data with the chosen name, if any, when there is a match for this element, using a | separator between matches.
+* '''Event type:''' Optionally enable this text field to enter an event type name that will override the default (trace type) when this element is present.
Note: An element's extracted data 'value' is a parsed string representation of all its attributes, children elements and their own values. To extract more specific information from an element, ignore its data value and extract the data from one or many of its attributes and children elements.
* '''Attribute name:''' Enter a name for the attribute that must match an attribute of this element in the XML file.
* '''Name combo:''' Select a name for the extracted data:
-** '''Time Stamp''': Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Timestamp''': Select this option to identify the timestamp data. The input's data and time pattern must be entered in the format: text box.
+** '''Event type''': Select this option to identify the event type name. This will override the default or element-specific event type name.
** '''Message''': Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
** '''Other''': Select this option to identify any non-standard data. The name must be entered in the name: text box. It does not have to match the element name.
* '''Action combo:''' Select the action to be performed on the extracted data:
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 '''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'''.
+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. You can also enter directly the name of the events you want to enable (comma separated list and wildcards are supported). Finally press '''Ok'''.
[[Image:images/LTTng2TracepointEventsDialog.png]]
[[Image:images/LTTng2EnabledUstWildcardEvents.png]]
+When enabling '''Tracepoint''' with wildcard, it is possible to specify event(s) (comma separated list) that we want to '''exclude''' from that wildcard selection. To '''exclude''' '''Tracepoint''' events, check the corresponding '''Select''' check box, fill the '''Event Names''' field and press '''Ok'''.
+
+[[Image:images/LTTng2UstExcludeEventsDialog.png]]
+
For UST it is possible to enable '''Tracepoint''' events using log levels. To enable '''Tracepoint''' events using log levels, select first the corresponding '''Select''' button, select a log level from the drop down menu, fill in the relevant information (see below) and press '''Ok'''.
* '''Event Name''': Name to display
** '''State''': The channel state ('''ENABLED''' or '''DISABLED''')
** '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
** '''Switch Timer Interval''': The switch timer interval.
+** '''Number of Discarded Events''': The number of discarded events of the channel.
+** '''Number of Lost Packets''': The number of lost packets of the channel.
* '''Event''' Properties (Channel)
** '''Event Name''': The name of the event.
** '''Event Type''': The event type ('''TRACEPOINT''', '''SYSCALL''' or '''PROBE''').
The following mouse actions are available:
* '''left-click''': select a time or time range begin time
-* '''Shift-left-click''': select a time range end time
+* '''Shift-left-click or drag''': Extend or shrink the selection range
+
* '''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]]
| Resets the zoom window to the full range.
|-
| [[Image:images/prev_event.gif]]
-| Select Previous Event
+| Select Previous State Change
| Selects the previous state for the selected process. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/next_event.gif]]
-| Select Next Event
+| Select Next State Change
| Selects the next state for the selected process. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/add_bookmark.gif]]
| Resets the zoom window to the full range.
|-
| [[Image:images/prev_event.gif]]
-| Select Previous Event
+| Select Previous State Change
| Selects the previous state for the selected resource. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/next_event.gif]]
-| Select Next Event
+| Select Next State Change
| Selects the next state for the selected resource. Pressing the '''Shift''' key at the same time will update the selection end time of the current selection range.
|-
| [[Image:images/add_bookmark.gif]]
The CPU Usage chart is usable with the mouse. The following actions are set:
* '''left-click''': select a time or time range begin time
-* '''left-drag horizontally''': select a time range or change the time range begin or end time
-* '''middle-drag''': pan left or right
-* '''right-drag horizontally''': zoom region
-* '''mouse wheel up/down''': zoom in or out
+* '''Shift-left-click or drag''': Extend or shrink the selection range
+* '''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]]
+* '''Shift-mouse wheel up/down''': scroll left or right
+* '''Ctrl-mouse wheel up/down''': zoom in or out horizontally
==== Tooltips ====
The Relative Kernel Memory chart is usable with the mouse. The following actions are set:
* '''left-click''': select a time or time range begin time
+* '''Shift-left-click or drag''': Extend or shrink the selection range
+
* '''left-drag horizontally''': select a time range or change the time range begin or end time
-* '''middle-drag''': pan left or right
-* '''right-drag horizontally''': zoom region
-* '''mouse wheel up/down''': zoom in or out
+* '''middle-drag or Ctrl-left-drag horizontally''': pan left or right
+* '''right-drag horizontally''': [[#Zoom region|zoom region]]
+* '''Shift-mouse wheel up/down''': scroll left or right
+* '''Ctrl-mouse wheel up/down''': zoom in or out horizontally
==== Tooltips ====
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. Note that pressing the '''Shift''' key at the same time will update the selection end time of the current selection.
+Clicking the '''Select Next State Change''' or '''Select Previous State Change''' 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. Note that pressing the '''Shift''' key at the same time will update the selection end time of the current selection.
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.
The Memory Usage chart is usable with the mouse. The following actions are set:
* '''left-click''': select a time or time range begin time
+* '''Shift-left-click or drag''': Extend or shrink the selection range
+
* '''left-drag horizontally''': select a time range or change the time range begin or end time
-* '''middle-drag''': pan left or right
-* '''right-drag horizontally''': zoom region
-* '''mouse wheel up/down''': zoom in or out
+* '''middle-drag or Ctrl-left-drag horizontally''': pan left or right
+* '''right-drag horizontally''': [[#Zoom region|zoom region]]
+* '''Shift-mouse wheel up/down''': scroll left or right
+* '''Ctrl-mouse wheel up/down''': zoom in or out horizontally
=== Toolbar ===
Select an XML file from the list, click the '''Export''' button and enter or select a file in the opened file dialog to export the XML analysis. Note that if an existing file containing an analysis is selected, its content will be replaced with the analysis to export.
+* Edit
+
+Select an XML file from the list, click the '''Edit''' to open the XML editor. When the file is saved after being modified, it is validated and traces that are affected by this file are closed.
+
* Delete
Select an XML file from the list and click the '''Delete''' button to remove the XML file. Deleting an XML file will close all the traces for which this analysis applies and remove the analysis.
projects / deliverable / tracecompass.git / blobdiff