* Support for arbitrarily large traces (larger than available memory)
* Support for correlating multiple time-ordered traces
* Support for zooming down to the nanosecond on any part of a trace or set of traces
-* Views synchronization of currently selected event
+* Views synchronization of currently selected time or time range, and window time range
* Efficient searching and filtering of events
* Support for trace bookmarks
The highlighted event is the ''current event'' and is synchronized with the other views. If you select another event, the other views will be updated accordingly. The properties view will display a more detailed view of the selected event.
+An event range can be selected by holding the '''Shift''' key while clicking another event or using any of the cursor keys ('''Up'''', '''Down''', '''PageUp''', '''PageDown''', '''Home''', '''End'''). The first and last events in the selection will be used to determine the current selected time range for synchronization with the other views.
+
[[Image:images/LTTng2EventProperties.png]]
The Events editor can be closed, disposing a trace. When this is done, all the views displaying the information will be updated with the trace data of the next event editor tab. If all the editor tabs are closed, then the views will display their empty states.
[[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:
-* '''Current Event (sec)''': Displays the timestamp of the currently selected event
+* '''Current Event (sec)''': Displays the current time or selected time range begin time
* '''Window Span (sec)''': Displays the current time range window size
Both control can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly.
-
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 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.
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.
-The dashed vertical magenta bar, on the right, shows the position of the last event. The dashed vertical red bar shows the relative position of the currently selected event. The current event can be changed by clicking on the histogram.
+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.
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.
* '''Left''': Moves the current event to the previous non-empty bar
* '''Right''': Moves the current event to the next non-empty bar
-* '''Home''': Displays the current event to the first histogram bar
-* '''End''': Displays the current event to the last non-empty histogram bar
+* '''Home''': Sets the current time to the first histogram bar
+* '''End''': Sets the current time to the last non-empty histogram bar
== Statistics View ==
The filters can be more complex than what can be achieved with the filter header row in the events table. The filter is defined in a tree node structure, where the node types can be any of '''EVENTTYPE''', '''AND''', '''OR''', '''CONTAINS''', '''EQUALS''', '''MATCHES''' or '''COMPARE'''. Some nodes types have restrictions on their possible children in the tree.
-The '''EVENTTYPE''' node filters against the event type of the trace as defined in a plugin extension or in a custom parsers. When used, any child node will have its field combo box restricted to the possible fields of that event type.
+The '''EVENTTYPE''' node filters against the event type of the trace as defined in a plug-in extension or in a custom parsers. When used, any child node will have its field combo box restricted to the possible fields of that event type.
The '''AND''' node applies the logical ''and'' condition on all of its children. All children conditions must be true for the filter to match. A ''not'' operator can be applied to invert the condition.
When a filter is applied in the events table, the non-matching ticks are removed from the Time Chart view.
-The Time Chart only supports traces that are opened in an editor. The use of an editor is specified in the plugin extension for that trace type, or is enabled by default for custom traces.
+The Time Chart only supports traces that are opened in an editor. The use of an editor is specified in the plug-in extension for that trace type, or is enabled by default for custom traces.
== Environment Variables View ==
A new feature of CTF traces is their ability to store user defined data that is not to be placed in an event. It is generally data that is per-trace specific, such as the tracer version and the trace domain. It will be populated when a trace is loaded if the trace has environment variables. <br>
The view shows a tree of currently selected traces and their registered state system IDs. For each state system the tree structure of attributes is displayed. The attribute name, quark, value, start and end time, and full attribute path are shown for each attribute.
-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).
+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.
== Call Stack View ==
Clicking on the time graph will set the current time and consequently update the table with the current call stack information.
+Shift-clicking on the time graph will select a time range. When the selection is a time range, the begin time is used to update the stack information.
+
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.
To create a session with advanced options, fill in the relevant parameters and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
+==== Creating a Snapshot Tracing Session ====
+LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After starting tracing the trace events are not stored on disk or over the network. They are only transfered to disk or over the network when the user records a snapshot. To create such a snapshot session, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]].
+
+[[Image:images/LTTng2CreateSessionDialog_Snapshot.png]]
+
+Fill in all necessary information, select checkbox for '''Snapshot Mode''' and press '''Ok'''. By default, the location for the snapshot output will be on the host where the host is located.
+
+Refer to chapter [[#Recording a Snapshot | Recording a Snapshot]] for how to create a snapshot.
+
==== Enabling Channels - General ====
Enabling channels can be done using a session tree node when the domain hasn't be created in the session or, alternatively on a domain tree node of a session in case the domain is already available.
[[Image:images/LTTng2CreateChannelDialog.png]]
-By default the domain '''Kernel''' is selected and the corresponding default values are shown. To create a UST channel, select '''UST''' under the domain section. To get the default values of UST, then press button '''Default'''.
+By default the domain '''Kernel''' is selected. To create a UST channel, select '''UST''' under the domain section. The label <Default> in any text box indicates that the default value of the tracer will be configured. To initialize the dialog box press button '''Default'''.
If required update the following channel information and then press '''Ok'''.
* '''Channel Name''': The name of the channel.
-* '''Number of Sub Buffers''': The number of sub-buffers of the channel.
-* '''Overwrite Mode''': The channel overwrite mode ('''true''' or '''false''')
-* '''Read Timer Interval''': The read timer interval.
* '''Sub Buffer size''': The size of the sub-buffers of the channel (in bytes).
+* '''Number of Sub Buffers''': The number of sub-buffers of the channel.
* '''Switch Timer Interval''': The switch timer interval.
+* '''Read Timer Interval''': The read timer interval.
+* '''Discard Mode''': '''Overwrite''' events in buffer or '''Discard''' new events when buffer is full.
Upon successful operation, the requested domain will be created under the session tree node as well as the requested channel will be added under the domain. The channel will be '''ENABLED'''.
+==== Configuring Trace File Rotation ====
+
+Since LTTng Tools v2.2.0 it is possible to set the maximum size of trace files and the maximum number of them. These options are located in the same dialog box that is used for enabling channels.
+
+[[Image:images/LTTng2CreateChannelDialogFileRotation.png]]
+
+* '''Maximum size of trace files''': The maximum size of trace files
+* '''Maximum number of trace files''': The maximum number of trace files
+
+==== Configuring per UID and per PID Buffers (UST only) ====
+
+Since LTTng Tools v2.2.0 it is possible to configure the type of buffers for '''UST''' application. It is now possible to choose between per '''UID''' buffers (per user ID) and per '''PID''' buffers (per process ID) using the dialog box for enabling channels.
+
+[[Image:images/LTTng2CreateChannelDialogPerUIDBuffers.png]]
+
+* '''Per PID buffers''': To activate the per PID buffers option for UST channels
+* '''Per UID buffers''': To activate the per UID buffers option for UST channels
+
+If no buffer type is selected then the default value of the tracer will be configured.
+
+Note that '''Global shared buffers''' is only for kernel channel and is pre-selected when '''Kernel''' is selected in the dalog box.
+
+==== Configuring Periodical Flush for metadata Channel ====
+
+Since LTTng Tools v2.2.0 it is possible to configure periodical flush for the metadata channel. To set this, use the checkbox '''Configure metadata channel''' then fill the switch timer interval.
+
+[[Image:images/LTTng2CreateChannelDialogMetadataFlush.png]]
+
==== Enabling Channels On Domain Level ====
Once a domain is available, channels can be enabled directly using the domain. To enable a channel under an existing domain, select the tree node of the relevant domain and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
[[Image:images/LTTng2CreateChannelOnDomainAction.png]]
-The dialog box for enabling channel will open for entering information about the channel to be created. Note that the domain is pre-selected and cannot be changed.
-
-[[Image:images/LTTng2CreateChannelOnDomainDialog.png]]
-
-Fill the relevant information and press '''Ok'''.
+The dialog box for enabling channel will open for entering information about the channel to be created. Note that the domain is pre-selected and cannot be changed. Fill the relevant information and press '''Ok'''.
==== Enabling and Disabling Channels ====
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]]
Upon successful operation, the tracing session will be '''ACTIVE''' and the icon of the session will be updated.
+==== Recording a Snapshot ====
+
+LTTng Tools version v2.3.0 introduces the possibility to create snapshot tracing sessions. After creating a snapshot session (see [[#Creating a Snapshot Tracing Session | Creating a Snapshot Tracing Session]]) and starting tracing (see [[#Start Tracing | Start Tracing]]) it possible to record snapshots. To record a snapshot select one or more sessions and press the '''Record Snapshot''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Recored Snapshot''' menu item.
+
+[[Image:images/LTTng2RecordSnapshotAction.png]]
+
+This action can be executed many times. It is possible to import the recorded snpshots to a tracing project. The trace session might be '''ACTIVE''' or '''INACTIVE''' for that. Refer to section [[#Importing Session Traces to a Tracing Project | Importing Session Traces to a Tracing Project]] on how to import a trace to a tracing project.
+
==== Stop Tracing ====
-To stop tracing, select one or more sessions to stop in the Control View and press the '''Stop''' button. Alternatively, click the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Stop''' menu item.
+To stop tracing, select one or more sessions to stop in the Control View and press the '''Stop''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Stop''' menu item.
[[Image:images/LTTng2StopTracingAction.png]]
[[Image:images/LTTng2ImportDialog.png]]
-Select the trace to be imported by selecting the relevant traces in the tree viewer, select a tracing project from the '''Available Projects''' combo box and select the Overwrite button ('''Overwrite existing trace without warning''') if required. Then press button '''Ok'''. Upon successful import operation the the selected traces will be stored in the '''Traces''' directory of the specified tracing project. 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.
'''Note''': If the overwrite button ('''Overwrite existing trace without warning''') was not selected and a trace with the same name of a trace to be imported already exists in the project, then a new confirmation dialog box will open.
==== Importing Network Traces to a Tracing Project ====
-Since LTTng Tools v2.1.0 it is possible to store traces over the network. To import network traces, execute the '''Import''' action as described in chapter [[#Importing Session Traces to a Tracing Project|Importing Session Traces to a Tracing Project]]. For network traces a dialog will open for selecting a project from the list of available tracing projects within the current Eclipse workspace.
-
-[[Image:images/LTTng2ImportSelectTracingProjectDialog.png]]
-
-Select a tracing project from the drop-down menu and then click on '''Next...'''. This will open the default dialog box for importing traces to a tracing project. Follow the instructions in chapter [[#Importing Traces in a Project|Importing Traces in a Project]] to import the network traces of the current session.
+Since LTTng Tools v2.1.0 it is possible to store traces over the network. To import network traces, execute the '''Import''' action as described in chapter [[#Importing Session Traces to a Tracing Project|Importing Session Traces to a Tracing Project]]. For network traces the '''Batch Import Trace Wizard''' will be displayed. Follow the instructions in chapter [[#Batch Importing|Batch Importing]] to import the network traces of the current session.
=== Properties View ===
** '''Log Level''': The log level of the event.
* '''Session''' Properties
** '''Session Name''': The name of the Session.
-** '''Session Path''': The path on the remote host where the traces will be stored.
+** '''Session Path''': The path on the remote host where the traces will be stored. (Not shown for snapshot sessions).
** '''State''': The state of the session ('''ACTIVE''' or '''INACTIVE''')
+** '''Snapshot ID''': The snapshot ID. (Only shown for snapshot sessions).
+** '''Snapshot Name''': The name of the snapshot output configuration. (Only shown for snapshot sessions).
+** '''Snapshot Path''': The path where the snapshot session is located. (Only shown for snapshot sessions).
* '''Domain''' Properties
** '''Domain Name''': The name of the domain.
+** '''Buffer Type''': The buffer type of the domain.
* '''Channel''' Properties
** '''Channel Name''': The name of the channel.
** '''Number of Sub Buffers''': The number of sub-buffers of the channel.
== Control Flow View ==
-The '''''Control Flow View''''' is a LTTng-specific view that shows per-process events graphically. To enable it, select ''Control Flow'' under ''LTTng'' within the ''Show View'' window ('''Window''' -> '''Show View''' -> '''Other...'''):
+The '''''Control Flow''''' view is a LTTng-specific view that shows per-process events graphically. To enable it, select ''Control Flow'' under ''LTTng'' within the ''Show View'' window ('''Window''' -> '''Show View''' -> '''Other...'''):
[[Image:images/Cfv_show_view.png]]
[[Image:images/Cfv_global.png]]
-The view is divided into the following important sections: '''<span style="color: #C84545;">process tree</span>''', '''<span style="color: #A1C81A;">process TID, PTID and birth time</span>''', '''<span style="color: #67A3DC;">states flow</span>''' and the '''<span style="color: #AD77D7;">toolbar</span>'''.
+The view is divided into the following important sections: '''process tree and information''', '''control flow''' and the '''toolbar'''.
The following sections provide detailed information for each part of the Control Flow View.
-=== Process tree and informations ===
+=== Process tree and information ===
Processes are organized as a tree within this view. This way, child and parent processes are easy to identify.
The layout is based on the states computed from the trace events.
-A given process may be shown at different places within the tree since the nodes are '''unique (TID, birth time) couples'''. This means that if process B of parent A dies, you'll still see it in the tree. If process A forks process B again, it will be shown as a different node since it won't have the same birth time (and probably not the same TID). This has the advantage that the tree, once loaded, never changes: horizontal scrolling within the [[#States flow|states flow]] remains possible.
+A given process may be shown at different places within the tree since the nodes are '''unique (TID, birth time) couples'''. This means that if process B of parent A dies, you'll still see it in the tree. If process A forks process B again, it will be shown as a different node since it won't have the same birth time (and probably not the same TID). This has the advantage that the tree, once loaded, never changes: horizontal scrolling within the [[#Control flow|control flow]] remains possible.
The TID column shows the process node's '''thread ID''' and the PTID column shows its '''parent thread ID''' (nothing is shown if the process has no parent).
-=== States flow ===
+=== Control flow ===
This part of the Control Flow View is probably the most interesting one. Using the mouse, you can navigate through the trace (go left, right) and zoom on a specific region to inspect its details.
This dark yellow is what you'll see most of the time since scheduling puts processes on hold while others run.
-The vertical blue line is the '''current time indicator'''.
+The vertical blue line with T1 above it is the '''current selection indicator'''. When a time range is selected, the region between the begin and end time of the selection will be shaded and two lines with T1 and T2 above will be displayed. The time stamps corresponding to T1, T2 and their delta are shown in the status line when the mouse is hovering over the control flow.
+
+Arrows can be displayed that follow the execution of each CPU across processes. The arrows indicate when the scheduler switches from one process to another for a given CPU. The CPU being followed is indicated on the state tooltip. When the scheduler switches to and from the idle process, the arrow skips to the next process which executes on the CPU after the idle process. Note that an appropriate zoom level is required for all arrows to be displayed.
+
+The display of arrows is optional and can be toggled using the '''Hide Arrows''' toolbar button. It is also possible to follow a CPU's execution across state changes and the scheduler's process switching using the '''Follow CPU Forward/Backward''' toolbar buttons.
==== Using the mouse ====
The states flow is usable with the mouse. The following actions are set:
-* '''drag horizontally''': pan left or right
+* '''left-click''': select a time or time range begin time
+* '''Shift-left-click''': select a time range end time
+* '''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]]
* '''click on a colored bar''': the associated process node is selected and the current time indicator is moved where the click happened
* '''mouse wheel up/down''': zoom in or out
-* '''drag the time ruler horizontally''': zoom in or out
-* '''drag the time ruler horizontally with the right button''': [[#Zoom region|zoom region]]
-* '''double-click the time ruler''': reset zoom
+* '''drag the time ruler horizontally''': zoom in or out with fixed start time
+* '''double-click the time ruler''': reset zoom to full range
When the current time indicator is changed (when clicking in the states flow), all the other views are '''synchronized'''. For example, the [[#LTTng_Kernel_Events_Editor|Events Editor]] will show the event matching the current time indicator. The reverse behaviour is also implemented: selecting an event within the Events View will update the Control Flow View current time indicator.
==== Zoom region ====
-To zoom in on a specific region, '''right-click and drag the time ruler''' in order to draw a time range:
+To zoom in on a specific region, '''right-click and drag''' in order to draw a time range:
[[Image:images/Cfv_zoom_region.png]]
* the process name
* the pointed state name
+* the CPU (if applicable)
+* the system call name (if applicable)
* the pointed state date and start/stop times
* the pointed state duration (seconds)
The Control Flow View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
-[[Image:images/Cfv_toolbar.png]]
-
-The '''Previous event''' and '''Next event''' buttons update the current time indicator so that it's on the previous or next event.
-
-The '''Previous process''' and '''Next process''' buttons select the previous and next process node within the process tree.
-
-The '''Process filter''' buttons opens a new dialog box for configuring the processes to show.
-
-[[Image:images/LTTng2_CFV_Filter.png]]
+{|
+| [[Image:images/filter_items.gif]]
+| Show View Filter
+| Opens the process filter dialog
+|-
+| [[Image:images/show_legend.gif]]
+| Show Legend
+| Displays the states legend
+|-
+| [[Image:images/home_nav.gif]]
+| Reset the Time Scale to Default
+| Resets the zoom window to the full range
+|-
+| [[Image:images/prev_event.gif]]
+| Select Previous Event
+| Selects the previous state for the selected process
+|-
+| [[Image:images/next_event.gif]]
+| Select Next Event
+| Selects the next state for the selected process
+|-
+| [[Image:images/prev_menu.gif]]
+| Select Previous Process
+| Selects the previous process
+|-
+| [[Image:images/next_menu.gif]]
+| Select Next Process
+| Selects the next process
+|-
+| [[Image:images/zoomin_nav.gif]]
+| Zoom In
+| Zooms in on the selection by 50%
+|-
+| [[Image:images/zoomout_nav.gif]]
+| Zoom Out
+| Zooms out on the selection by 50%
+|-
+| [[Image:images/hide_arrows.gif]]
+| Hide Arrows
+| Toggles the display of arrows on or off
+|-
+| [[Image:images/follow_arrow_bwd.gif]]
+| Follow CPU Backward
+| Selects the previous state following CPU execution across processes
+|-
+| [[Image:images/follow_arrow_fwd.gif]]
+| Follow CPU Forward
+| Selects the next state following CPU execution across processes
+|}
== Resources View ==
+
This view is specific to kernel trace. To open it, go in '''Window''' -> '''Show View''' -> '''Other...''' and select '''LTTng/Resources''' in the list.
[[Image:images/Rv_example.png| Example of resources view with all trace points and syscalls enabled]]
The Resources View '''toolbar''', located at the top right of the view, has shortcut buttons to perform common actions:
-[[Image:images/Rv_toolbar.png]]
-
-The '''Previous event''' and '''Next event''' buttons update the current time indicator so that it's on the previous or next event.
-
-The '''Previous resource''' and '''Next resource''' buttons select the previous and next resource node within the resource tree.
+{|
+| [[Image:images/show_legend.gif]]
+| Show Legend
+| Displays the states legend
+|-
+| [[Image:images/home_nav.gif]]
+| Reset the Time Scale to Default
+| Resets the zoom window to the full range
+|-
+| [[Image:images/prev_event.gif]]
+| Select Previous Event
+| Selects the previous state for the selected resource
+|-
+| [[Image:images/next_event.gif]]
+| Select Next Event
+| Selects the next state for the selected resource
+|-
+| [[Image:images/prev_menu.gif]]
+| Select Previous Resource
+| Selects the previous resource
+|-
+| [[Image:images/next_menu.gif]]
+| Select Next Resource
+| Selects the next resource
+|-
+| [[Image:images/zoomin_nav.gif]]
+| Zoom In
+| Zooms in on the selection by 50%
+|-
+| [[Image:images/zoomout_nav.gif]]
+| Zoom Out
+| Zooms out on the selection by 50%
+|}
== LTTng Kernel Events Editor ==
* '''Current Format''' a format string generated by the page
* '''Sample Display''' an example of a timestamp formatted with the '''Current Format''' string.
+* '''Time Zone''' the time zone to use when displaying the time. The value '''Local time''' corresponds to the local, system-configured, time zone.
* '''Data and Time format''' how to format the date (days/months/years) and the time (hours/minutes/seconds)
* '''Sub-second format''' how much precision is shown for the sub-second units
* '''Date delimiter''' the character used to delimit the date units such as months and years
projects / deliverable / tracecompass.git / blobdiff