| LTTng Tracer Control | ||
|---|---|---|
|
|
|
|
| LTTng Perspective | Limitations | |
The LTTng Eclipse integration supports LTTng Tracer toolchains version v0.x as well as the version v2.0 (or later).
The LTTng Tracer toolchains version v0.x requires and LTTng agent running on the remote host. The functions to control the LTTng tracer (e.g. start, pause, resume), either locally or remotely, are available from the Remote Systems view (See Remote Systems View, an RSE view).
The LTTng tracer is controlled by the UI through an LTTng agent running on the tracer system.
A new connection to a remote system can be created using the new connection wizard of the Remote System Explorer. For this, a toolbar button exists on the top left corner of the Remote System view. Alternatively, this wizard can be started using File -> New -> Other ... -> Remote System Explorer -> Connection).
For LTTng control, select connection type LTTng and press Next to define the connection.
The Host name holds the IP address or DNS name of the remote system. The Connection name is the name to be displayed in the Remote Systems view. The Description is optional. Unless the user wants to use a specific Profile, the default profile is sufficient. The checkbox Verfiy host name enable or disables the verification of the remote system.
By default, when pressing "Finish" the new connection contains the following sub systems:
The user has the possibility to configure or omit the subsystems Files, Processes, Shells and Terminals by pressing "Next" and deselecting the relevant subsystem.
After finishing the new connection the Remote System view will be updated:
All actions are on elements in the Remote Systems view are accessible through context sensitive menu. By selecting a tree element and pressing the right mouse button a context sensitive menu is shown. Some of the actions are also available through toolbar buttons and toolbar menu.
The connection to the remote host can be established by selecting the connection in the tree, click the right mouse button and select Connect.
A login dialog will be opened, where the user needs to specify the user name and password.
After logging in the LTTng Trace Control will retrieve LTTng Remote System information. First it will read the supported providers. The providers will be one or both of the following: "kernel" for kernel tracing and "ust" for user space tracing. After that the trace controls reads the currently available targets. For kernel tracing, there is only one target with ID "0". For user space tracing each target is the corresponding process ID of a user space application with user space tracing enabled. Without any traces created the Remote System view will look like this (after expanding the tree):
The marker of a given target can be configured by selecting the kernel target "0", clicking the right mouse button and selecting the Configure Markers menu item of the context sensitive menu.
A new dialog box will show for the configuration of the relevant markers. All markers are listed in a table. The first column contains a checkbox to enable or disable a marker. The second column shows the name of the marker and all other columns display marker details.
A new trace can be created by selecting the kernel target "0", clicking the right mouse button and selecting the New Trace menu item of the context sensitive menu.
A new dialog box will show for the configuration of the relevant parameter.
If all inputs are valid the Finish button will be active and can be used to create the trace. The LTTng trace control will setup the trace using the connection to the remote agent.
After creating a new trace, the Remote Systems view will be updated. When selecting the newly created trace in the tree, the buttons to start, stop and configure the trace will be enabled.
Some of the trace parameters can be changed if the trace has not been previously started. A trace can be configured by selecting the relevant kernel trace, clicking the right mouse button and selecting the "Configure Trace" menu item of the context sensitive menu.
A new dialog box with a wizard page will show for the configuration of the relevant parameter. For explanation of the parameters see Create_a_New_Kernel_Trace
After entering valid parameters the Next and Finish buttons will be active. To finalize the configuration of the trace select the Finish button. To configure channel parameters select the Next button. A new wizard page will show for the configuration of channel parameters. For provider kernel the following display will show:
All channels can be configured at once by clicking the right mouse button in the table and selecting one of the menu items of the context sensitive menu.
For provider ust only the channel parameter Channel Timer can be configured and the following display will show after selecting the Next button of the Trace configuration page.
Please note that channel parameters cannot be retrieved from the LTTng agent. Therefore they cannot be displayed in the table unless they have been previously configured through Eclipse. However, this information will be lost after closing Eclipse. A question mark will indicate that the relevant value is not known and it will be ignored after selecting the Finish button.
Please note that the Configure Trace item of the context sensitive menu of a trace can be used to display the trace and channel parameters at any time. However, they can only be changed if the trace has not been previously started.
A configured or paused trace can be started by selecting the kernel trace, clicking the right mouse button and selecting the Start menu item of the context sensitive menu. Alternatively, the start button in the toolbar can be used to start the trace. If the trace location is host (streaming trace), it will be automatically added to the tracing project that was selected at trace creation.
A started trace can be paused by selecting the relevant trace, clicking the right mouse button and selecting the Pause menu item of the context sensitive menu. Alternatively, the pause button in the toolbar can be used to pause the trace.
A non-started trace can be stopped by selecting the relevant trace, clicking the right mouse button and selecting the Stop menu item of the context sensitive menu. Alternatively, the stop button in the toolbar can be used to stop the trace. This will destroy the trace on the remote system, all allocated memory will be deallocated and all relevant trace files will be finalized. This step is need to be able to import a trace into the LTTng Perspective.
A streaming or stopped trace can be imported to the LTTng Perspective for viewing by selecting the relevant trace, clicking the right mouse button and selecting the Import To Project menu item of the context sensitive menu. A new dialog box will show to select the LTTng Project.
For local trace path (streamed to the host):
For remote trace path (stored on the target):
After pressing button Import the trace will be stored in the selected project. For a trace stored on the target, it will be downloaded from the remote system.
A stopped trace can be deleted by selecting the relevant trace, clicking the right mouse button and selecting the Delete menu item of the context sensitive menu. A new dialog box will show for the user to confirm that the selected trace should be deleted.
The Property view displays the properties of the selected resource in the tree. For traces it displays all configuration parameters.
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 corressponding 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.
To open the Control View, select ' Window->Show View->Other...->LTTng->Control View.
To connect to a remote host, select the New Connection button in the Control View.
A new display will show for entering the remote host information. A drop down menu will filled with all existing host information which were used before. To enter the host information either select one of the hosts in the drop down menu or enter the host information manually.
To use an existing connection definition, select the relevant entry in the drop-down menu and then select Ok.
To enter the host information manually select first the button Edit connection information. Then the text fields Connection Name and Host Name will enabled. Enter the relevant information and then select Ok.
A new display will show for providing the user name and password. This display only opens if no password had been saved before. Enter user name and password in the Enter Password dialog box and select Ok.
The Host Name holds the IP address or DNS name of the remote system. The Connection Name is the alias name to be displayed in the Control View.
After pressing Ok the SSH connection will be established and after successful login the Control View implementation retrieves the LTTng Tracer Control information. This information will be displayed in the Control View in form of a tree structure.
The top level tree node is the representation of the remote connection (host). The connection name of the connection will be displayed. Depending on the connection state different icons are displayed. If the node is
CONNECTED the icon is shown
, otherwise (states
CONNECTING,
DISCONNNECTING or
DISCONNECTED the icon is
.
Under the host level two folder groups are located. The first one is the Provider group. The second one is the Sessions group.
Under the Provider group all trace providers are displayed. Trace providers are Kernel and any user space application that supports UST tracing. Under each provider a corresponding list of events are displayed.
Under the Sessions group all current sessions will be shown. The level under the sessions show the configured domains. Currently the LTTng 2.0 Tracer Toolchan supports domain Kernel and UST global. Under each domain the configured channels will be displayed. The last level is under the channels where the configured events are displayed.
Each session can be
ACTIVE or
INACTIVE. Active means that tracing has been started, inactive means that the tracing has been stopped. Depending on the state of a session a different icon is displayed. The icon for an active session is
. The icon for an inactive session is
.
Each channel can be
ENABLED or
DISABLED. An enabled channel means that all configured events of that channel will be traced and a disabled channel won't trace any of its configured events. Different icons are displayed depending on the state of the channel. The icon for an enabled channel is
and the icon for a disabled channel is
.
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
and a disabled event the icon
.
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.
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.
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.
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.
A dialog box will open for entering information about the session to be created.
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.
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.
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.
A dialog box will open for entering information about the channel to be created.
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.
If required update the following channel information and then press Ok.
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.
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.
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 successsful operation, the selected channels will be DISABLED and the icons for the channels will be updated.
To enable one or more disabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the Enable Channel menu item of the context-sensitive menu.
Upon successsful operation, the selected channels will be ENABLED and the icons for the channels will be updated.
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.
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.
A dialog box will open for entering information about events to be enabled.
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.
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 requested events of type TRACEPOINT under the channel. The channel and events will be ENABLED.
To enable all Syscalls, select the corresponding Select button and press Ok.
Upon successful operation, the event with the name syscalls and event type SYSCALL will be added under the default channel (channel0). If necessary the domain Kernel and the channel channel0 will be created.
To enable a Dynamic Probe event, select the corresponding Select button, fill the Event Name and Probe fields and press Ok. Note that the probe can be an address, symbol or a symbol+offset where the address and offset can be octal (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...).
Upon successful operation, the dynamic probe event with the given name and event type PROBE will be added under the default channel (channel0). If necessary the domain Kernel and the channel channel0 will be created.
To enable a Dynamic Function entry/return Probe event, select the corresponding Select button, fill the Event Name and Function fields and press Ok. Note that the funtion probe can be an address, symbol or a symbol+offset where the address and offset can be octal (0NNN...), decimal (NNN...) or hexadecimal (0xNNN...).
Upon successful operation, the dynamic function probe event with the given name and event type PROBE will be added under the default channel (channel0). If necessary the domain Kernel and the channel channel0 will be created.
For enabling UST events, first open the enable events dialog as described in section Enabling Kernel Events On Session Level and select domain UST.
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.
Upon successful operation, the domain UST global 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 requested events under the channel. The channel and events will be ENABLED. Note that for the case that All tracepoints were selected the wildcard * is used which will be shown in the Control View as below.
For UST it is possible to enable Tracepoint events using a wildcard. To enable Tracepoint events with a wildcard, select first the corresponding Select button, fill the Wildcard field and press Ok.
Upon successful operation, the event with the given wildcard and event type TRACEPOINT will be added under the default channel (channel0). If necessary the domain UST global and the channel channel0 will be created.
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.
Upon successful operation, the event with the given event name and event type TRACEPOINT will be added under the default channel (channel0). If necessary the domain UST global and the channel channel0 will be created.
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.
To enable events for domain Kernel follow the instructions in section Enabling Kernel Events On Session Level, for domain UST global Enabling UST Events On Session Level.
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.
Kernel events can also be enabled on the channel level. If necessary, create a channel as described in sections Creating Channels On Session Level or Creating Channels On Domain Level.
Then select the relevant channel tree node, click the right mouse button and the select Enable Event.... 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.
To enable events for domain Kernel follow the instructions in section Enabling Kernel Events On Session Level, for domain UST global Enabling UST Events On Session Level.
When enabling events on the channel level, the events will be add to the selected channel.
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.
Upon successsful operation, the selected events will be DISABLED and the icons for these events will be updated.
To enable one or more disabled events, select the tree nodes of the relevant events and press the right mouse button. Then select the Enable Event menu item of the context-sensitive menu.
Upon successsful operation, the selected events will be ENABLED and the icons for these events will be updated.
Note: There is currently a limitiation 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.
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. Also, if other than default channel channel0 is required, create a channel as described in sections Creating Channels On Session Level or Creating Channels On Domain Level.
To assign tracepoint events to a session and channel, select the events to be enabled under the provider (e.g. provider Kernel), click right mouse button and then select Enable Event... menu item from the context sesitive menu.
A new display will open for defining the session and channel.
Select a session from the Session List drop-down menu, a channel from the Channel List drop-down menu and the press Ok. Upon successful operation, the selected events will be added to the selected session and channel of the domain that the selected provider belongs to. In case that there was no channel available, the domain and the default channel channel0 will be created for corresponding session. The newly added events will be ENABLED.
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.
A new display will open for selecting one or more contexts to add.
The tree shows all avaiable context that can be added. Select one or more context and the press Ok. Upon successful operation, the selected context will be added to all channels and their events of the selected domain.
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. 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 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.
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. Upon successful operation, the selected context will be added to the selected event.
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.
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.
Upon successful operation, the tracing session will be INACTIVE and the icon of the session will be updated.
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.
A confirmation dialog box will open. Click on Ok to destroy the session otherwise click on Cancel.
Upon successful operation, the tracing session will be destroyed and removed from the tree.
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.
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 successfull 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.
To import traces from a tracing session, select the relevant session and click on the Import Button. Alternativly, click the right mouse button on the session tree node and select the menu item Import... from the context-sensitive menu.
A new display will open for selecting the traces to import.
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 analysed further.
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.
To Overwrite select the Overwrite Button and press Ok.
If the existing trace should not be overwritten select, then select the Rename option of the confirmation dialog box above, enter a new name and then press Ok.
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 follewed:
List of properties:
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 allows the user to configure the logging of LTTng 2.0 tracer control commands and results to a file.
To change the tracing group of the user which will be specified on each command line, enter the new group name in the Tracing Group text field and click ok. The default tracing group is tracing and can be restored by pressing the Restore Defaults button.
To configure logging of trace control commands and the corresponding command result to a file, selected the button Logging. To append to an existing log file, select the Append button. Deselect the Append button to overwrite any existing log file. It's possible to specify a verbose level. There are 3 levels with inceasing verbosity from Level 1 to Level 3. To change the verbosity level, select the relevant level or select None. If None is selected only commands and command results are logged. Then press on button Ok. The log file will be stored in the users home directory with the name lttng_tracer_control.log. The name and location cannot be changed. To reset to default preferences, click on the button Restore Defaults.
|
|
|
|
| LTTng Perspective | Limitations |