The trace will be opened in an editor showing the events table, and an entry will be added for it in the Time Chart view.
-== LTTng Tracer Control ==
+= LTTng Tracer Control =
The LTTng Tracer Control in Eclipse for the LTTng Tracer toolchain version v2.0 (or later) is done using SSH and requires an SSH server to be running on the remote host. For the SSH connection the SSH implementation of RSE is used. For that a new System Type was defined using the corresponding RSE extension. The functions to control the LTTng tracer (e.g. start and stop), either locally or remotely, are available from a dedicated Control View.
In the following sections the LTTng 2.0 tracer control integration in Eclipse is described. Please refer to the LTTng 2.0 tracer control command line manual for more details and descriptions about all commands and their command line parameters [[#References | References]].
-=== Control View ===
+== Control View ==
To open the Control View, select '''Window->Show View->Other...->LTTng->Control View''.
[[Image:images/LTTngControlView.png]]
-==== Creating a New Connection to a Remote Host ====
+=== Creating a New Connection to a Remote Host ===
To connect to a remote host, select the '''New Connection''' button in the Control View.
Events within a channel can be in state '''ENABLED''' or '''DISABLED'''. Enabled events are stored in the trace when passed during program execution. Disabled events on the other hand won't be traced. Depending on the state of the event the icons for the event is different. An enabled event has the icon [[Image:images/Event_enabled.gif]] and a disabled event the icon [[Image:images/Event_disabled.gif]].
-==== Disconnecting from a Remote Host ====
+=== Disconnecting from a Remote Host ===
To disconnect from a remote host, select the host in the Control View and press the '''Disconnect''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Disconnect''' button.
[[Image:images/LTTng2ControlViewDisconnect.png]]
-==== Connecting to a Remote Host ====
+=== Connecting to a Remote Host ===
To connect to a remote host, select the host in the Control View and press the '''Connect''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Connect''' button. This will start the connection process as discribed in [[#Creating a New Connection to a Remote Host | Creating a New Connection to a Remote Host]].
[[Image:images/LTTng2ControlViewConnect.png]]
-==== Deleting to a Remote Host Connection ====
+=== Deleting to a Remote Host Connection ===
To delete a remote host connection, select the host in the Control View and press the '''Delete''' button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the '''Delete''' button. For that command to be active the connection state has to be '''DISCONNECTED''' and the trace has to be closed.
[[Image:images/LTTng2ControlViewDelete.png]]
-==== Creating a Tracing Session ====
+=== Creating a Tracing Session ===
To create a tracing session, select the tree node '''Sessions''' and press the right mouse button. Then select the '''Create Session...''' button of the context-sensitive menu.
[[Image:images/LTTng2CreateSessionAction.png]]
Fill in the '''Session Name''' and optionally the '''Session Path''' and press '''Ok'''. Upon successful operation a new session will be created and added under the tree node '''Sessions'''.
-==== Creating a Tracing Session With Advanced Options ====
+=== Creating a Tracing Session With Advanced Options ===
LTTng Tools version v2.1.0 introduces the possibility to configure the trace output location at session creation time. The trace can be stored in the (tracer) local file system or can be transferred over the network.
To create a tracing session and configure the trace output, open the trace session dialog as described in chapter [[#Creating a Tracing Session | Creating a Tracing Session]]. A dialog box will open for entering information about the session to be created.
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 ====
+=== 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]]
Refer to chapter [[#Recording a Snapshot | Recording a Snapshot]] for how to create a snapshot.
-==== Enabling Channels - General ====
+=== 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.
-==== Enabling Channels On Session Level ====
+=== Enabling Channels On Session Level ===
To enable a channel, select the tree node of the relevant session and press the right mouse button. Then select the '''Enable Channel...''' button of the context-sensitive menu.
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 ====
+=== 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.
* '''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) ====
+=== 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.
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 ====
+=== 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 ====
+=== 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.
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 ====
+=== Enabling and Disabling Channels ===
To disable one or more enabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the '''Disable Channel''' menu item of the context-sensitive menu.
Upon successful operation, the selected channels will be '''ENABLED''' and the icons for the channels will be updated.
-==== Enabling Events - General ====
+=== Enabling Events - General ===
Enabling events can be done using different levels in the tree node. It can be done on the session, domain level and channel level. For the case of session or domain, i.e. when no specific channels is assigned then enabling of events is done on the default channel with the name '''channel0''' which created, if not already exists, by the LTTng tracer control on the server side.
-==== Enabling Kernel Events On Session Level ====
+=== Enabling Kernel Events On Session Level ===
To enable events, select the tree node of the relevant session and press the right mouse button. Then select the '''Enable Event (default channel)...''' button of the context-sensitive menu.
[[Image:images/LTTng2EnabledFunctionProbeEvent.png]]
-==== Enabling UST Events On Session Level ====
+=== Enabling UST Events On Session Level ===
For enabling UST events, first open the enable events dialog as described in section [[#Enabling Kernel Events On Session Level | Enabling Kernel Events On Session Level]] and select domain '''UST'''.
[[Image:images/LTTng2EnabledUstLoglevelEvents.png]]
-==== Enabling Events On Domain Level ====
+=== Enabling Events On Domain Level ===
Kernel events can also be enabled on the domain level. For that select the relevant domain tree node, click the right mouse button and the select '''Enable Event (default channel)...'''. A new dialog box will open for providing information about the events to be enabled. Depending on the domain, '''Kernel''' or '''UST global''', the domain specifc fields are shown and the domain selector is preselected and read-only.
When enabling events on the domain level, the events will be add to the default channel '''channel0'''. This channel will be created by on the server side if neccessary.
-==== Enabling Events On Channel Level ====
+=== Enabling Events On Channel Level ===
Kernel events can also be enabled on the channel level. If necessary, create a channel as described in sections [[#Enabling Channels On Session Level | Creating Channels On Session Level]] or [[#Enabling Channels On Domain Level | Creating Channels On Domain Level]].
When enabling events on the channel level, the events will be add to the selected channel.
-==== Enabling and Disabling Events ====
+=== Enabling and Disabling Events ===
To disable one or more enabled events, select the tree nodes of the relevant events and click the right mouse button. Then select '''Disable Event''' menu item in the context-sensitive menu.
'''Note''': There is currently a limitation for kernel event of type '''SYSCALL'''. This kernel event can not be disabled. An error will appear when trying to disable this type of event. A work-around for that is to have the syscall event in a separate channel and disable the channel instead of the event.
-==== Enabling Tracepoint Events From Provider ====
+=== Enabling Tracepoint Events From Provider ===
It is possible to enable events of type '''Tracepoint''' directly from the providers and assign the enabled event to a session and channel. Before doing that a session has to be created as described in section [[#Creating a Tracing Session | Creating a Tracing Session]]. Also, if other than default channel '''channel0''' is required, create a channel as described in sections [[#Enabling Channels On Session Level | Creating Channels On Session Level]] or [[#Enabling Channels On Domain Level | Creating Channels On Domain Level]].
[[Image:images/LTTng2AssignedEvents.png]]
-==== Configuring Filter Expression On UST Event Fields ====
+=== Configuring Filter Expression On UST Event Fields ===
Since LTTng Tools v2.1.0 it is possible to configure a filter expression on UST event fields. To configure a filter expression on UST event fields, open the enable event dialog as described in chapters [[#Enabling UST Events On Session Level | Enabling UST Events On Session Level]], [[#Enabling Events On Domain Level | Enabling Events On Domain Level]] or [[#Enabling Events On Channel Level | Enabling Events On Channel Level]], select UST if needed, select the relevant '''Tracepoint''' event(s) and enter the filter expression in the '''Filter Expression''' text field.
For the syntax of the filter expression refer to the '''LTTng Tracer Control Command Line Tool User Manual''' of chapter [[#References |References]].
-==== Adding Contexts to Channels and Events of a Domain ====
+=== Adding Contexts to Channels and Events of a Domain ===
It is possible to add contexts to channels and events. Adding contexts on channels and events from the domain level, will enable the specified contexts to all channels of the domain and all their events. To add contexts on the domain level, select a domain, click right mouse button on a domain tree node (e.g. provider '''Kernel''') and select the menu item '''Add Context...''' from the context-sensitive menu.
'''Note''': The LTTng UST tracer only supports contexts '''procname''', '''pthread_id''', '''vpid''' '''vtid'''. Adding any other contexts in the UST domina will fail.
-==== Adding Contexts to All Events of a Channel ====
+=== Adding Contexts to All Events of a Channel ===
Adding contexts on channels and events from the channel level, will enable the specified contexts to all events of the selected channel. To add contexts on the channel level, select a channel, click right mouse button on a channel tree node and select the menu item '''Add Context...''' from the context-sensitive menu.
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 an Event of a Specific Channel ====
+=== Adding Contexts to an Event of a Specific Channel ===
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.
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 the selected event.
-==== Start Tracing ====
+=== Start Tracing ===
To start tracing, select one or more sessions to start in the Control View and press the '''Start''' button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the '''Start''' menu item.
Upon successful operation, the tracing session will be '''ACTIVE''' and the icon of the session will be updated.
-==== Recording a Snapshot ====
+=== 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.
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 ====
+=== 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 node. A context-sensitive menu will show. Then select the '''Stop''' menu item.
Upon successful operation, the tracing session will be '''INACTIVE''' and the icon of the session will be updated.
-==== Destroying a Tracing Session ====
+=== Destroying a Tracing Session ===
To destroy a tracing session, select one or more sessions to destroy in the Control View and press the '''Destroy''' button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the '''Destroy...''' menu item. Note that the session has to be '''INACTIVE''' for this operation.
Upon successful operation, the tracing session will be destroyed and removed from the tree.
-==== Refreshing the Node Information ====
+=== Refreshing the Node Information ===
To refresh the remote host information, select any node in the tree of the Control View and press the '''Refresh''' button. Alternatively, click the right mouse button on any tree node. A context-sensitive menu will show. Then select the '''Refresh''' menu item.
Upon successful operation, the tree in the Control View will be refreshed with the remote host configuration.
-==== Quantifing LTTng overhead (Calibrate) ====
+=== Quantifing LTTng overhead (Calibrate) ===
The LTTng calibrate command can be used to find out the combined average overhead of the LTTng tracer and the instrumentation mechanisms used. For now, the only calibration implemented is that of the kernel function
instrumentation (kretprobes). To run the calibrate command, select the a domain (e.g. '''Kernel'''), click the right mouse button on the domain tree node. A context-sensitive menu will show. Select the '''Calibrate''' menu item.
Upon successful operation, the calibrate command is executed and relevant information is stored in the trace. Note: that the trace has to be active so that to command as any effect.
-==== Importing Session Traces to a Tracing Project ====
+=== Importing Session Traces to a Tracing Project ===
To import traces from a tracing session, select the relevant session and click on the '''Import''' Button. Alternatively, click the right mouse button on the session tree node and select the menu item '''Import...''' from the context-sensitive menu.
[[Image:images/LTTng2ImportDialog.png]]
-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.
+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. The session directory structure as well as the trace names will be preserved in the destination tracing project. For '''Kernel''' traces the trace type '''LTTng Kernel Trace''' and for '''UST''' traces the trace type '''LTTng UST 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.
+'''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 destination directory of the project, then a new confirmation dialog box will open.
[[Image:images/LTTng2ImportOverwriteConfirmationDialog.png]]
[[Image:images/LTTng2ImportRenameDialog.png]]
-==== Importing Network Traces to a Tracing Project ====
+=== 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 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 ===
+== Properties View ==
The Control View provides property information of selected tree component. Depending on the selected tree component different properties are displayed in the property view. For example, when selecting the node level the property view will be filled as followed:
* '''Event''' Properties (Channel)
** '''Event Name''': The name of the event.
** '''Event Type''': The event type ('''TRACEPOINT''', '''SYSCALL''' or '''PROBE''').
-** '''Log Level''': The log level of the event.
+** '''Log Level''': The log level of the event. (For LTTng Tools v2.4.0 or later, '''<=''' prior the log level name will indicate a range of log levels and '''==''' a single log level.)
** '''State''': The Event state ('''ENABLED''' or '''DISABLED''')
** '''Filter''': Shows '''with filter''' if a filter expression is configured else property '''Filter''' is omitted. (since support for LTTng Tools v2.1.0)
-=== LTTng Tracer Control Preferences ===
+== LTTng Tracer Control Preferences ==
Serveral LTTng 2.0 tracer control preferences exists which can be configured. To configure these preferences, select '''Window->Preferences''' from the top level menu. The preference display will open. Then select '''Tracing->LTTng Tracer Control Preferences'''. This preferences page allows the user to specify the tracing group of the user and to specify the command execution timeout as well as it allows the user to configure the logging of LTTng 2.0 tracer control commands and results to a file.
projects / deliverable / tracecompass.git / commitdiff
