org.eclipse.linuxtools.lttng.help/doc/LTTng.html

   1 <?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3         <head>
   4                 <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
   5                 <title>LTTng Plug-in User Guide - LTTng</title>
   6                 <link type="text/css" rel="stylesheet" href="book.css"/>
   7         </head>
   8         <body>
   9                 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
  10                         <tr>
  11                                 <th style="width: 100%" align="center" colspan="3">LTTng</th>
  12                         </tr>
  13                         <tr>
  14                                 <td style="width: 20%" align="left">
  15                                         <a href="Installation.html" title="Installation">
  16                                                 <img alt="Previous" border="0" src="images/prev.gif"/>
  17                                         </a>
  18                                 </td>
  19                                 <td style="width: 60%" align="center"></td>
  20                                 <td style="width: 20%" align="right">
  21                                         <a href="LTTng-Kernel-Analysis.html" title="LTTng Kernel Analysis">
  22                                                 <img alt="Next" border="0" src="images/next.gif"/>
  23                                         </a>
  24                                 </td>
  25                         </tr>
  26                         <tr>
  27                                 <td style="width: 20%" align="left" valign="top">Installation</td>
  28                                 <td style="width: 60%" align="center"></td>
  29                                 <td style="width: 20%" align="right" valign="top">LTTng Kernel Analysis</td>
  30                         </tr>
  31                 </table><hr/>
  32                 <h1 id="LTTng">LTTng</h1>
  33                 <h2 id="Tracing_Perspective">Tracing Perspective</h2>
  34                 <p>The
  35                         <b>Tracing</b> perspective is part of the
  36                         <b>Tracing and Monitoring Framework (TMF)</b> and groups the following views:
  37                 </p>
  38                 <ul>
  39                         <li>
  40                                 <a href="LTTng.html#Project_View">Project View</a>
  41                         </li>
  42                         <li>
  43                                 <a href="LTTng.html#Events_Editor">Events Editor</a>
  44                         </li>
  45                         <li>
  46                                 <a href="LTTng.html#Histogram_View">Histogram View</a>
  47                         </li>
  48                         <li>
  49                                 <a href="LTTng.html#Statistics_View">Statistics View</a>
  50                         </li>
  51                 </ul>
  52                 <p>The views are synchronized i.e. selecting an event, a timestamp, a time range, etc will update the other views accordingly.</p>
  53                 <p>
  54                         <img border="0" src="images/TracingPerspective.png"/>
  55                 </p>
  56                 <p>The perspective can be opened from the Eclipse Open Perspective dialog (
  57                         <b>Window &gt; Open Perspective... &gt; Other</b>).
  58                 </p>
  59                 <p>
  60                         <img border="0" src="images/ShowTracingPerspective.png"/>
  61                 </p>
  62                 <p>On top to these views, the
  63                         <b>Tracing and Monitoring Framework (TMF)</b> feature provides a set of generic tracing specific views, such as:
  64                 </p>
  65                 <ul>
  66                         <li>
  67                                 <a href="LTTng.html#Colors_View">Colors View</a>
  68                         </li>
  69                         <li>
  70                                 <a href="LTTng.html#Filters_View">Filters View</a>
  71                         </li>
  72                         <li>
  73                                 <a href="LTTng.html#Time_Chart_View">Time Chart View</a>
  74                         </li>
  75                         <li>
  76                                 <a href="LTTng.html#Environment_Variables_View">Environment Variables View</a>
  77                         </li>
  78                         <li>
  79                                 <a href="LTTng.html#Custom_Parser">Custom Parser</a>
  80                         </li>
  81                 </ul>
  82                 <p>To open one of the above
  83                         <b>Tracing</b> view, use the Eclipse Show View dialog (
  84                         <b>Window &gt; Show View &gt; Other...</b>. Then select the relevant view from the
  85                         <b>Tracing</b>.
  86                 </p>
  87                 <p>
  88                         <img border="0" src="images/ShowTracingViews.png"/>
  89                 </p>
  90                 <p>Additionally, the
  91                         <b>LTTng</b> feature provides a
  92                         <b>LTTng Tracer Control</b>. It comes with a  dedicated
  93                         <b>Control View</b>.
  94                 </p>
  95                 <ul>
  96                         <li>
  97                                 <a href="LTTng.html#LTTng_Tracer_Control">LTTng Tracer Control</a>
  98                         </li>
  99                 </ul>
 100                 <h2 id="Project_View">Project View</h2>
 101                 <p>The project view is the standard Eclipse Project Explorer.
 102                         <b>Tracing</b> projects are well integrated in the Eclipse's Common Navigator Framework. The Project Explorer shows
 103                         <b>Tracing</b> project with a small "T" decorator in the upper right of the project folder icon.
 104                 </p>
 105                 <h3 id="Creating_a_Tracing_Project">Creating a Tracing Project</h3>
 106                 <p>A new
 107                         <b>Tracing</b> project can be created using the New Tracing Project wizard. To create a new
 108                         <b>Tracing</b>  select
 109                         <b>File &gt; New &gt; Project...</b> from the main menu bar or alternatively form the context-sensitive menu (click with right mouse button in the
 110                         <b>Project Explorer</b>.
 111                 </p>
 112                 <p>The first page of project wizard will open. </p>
 113                 <p>
 114                         <img border="0" src="images/NewTracingProjectPage1.png"/>
 115                 </p>
 116                 <p>In the list of project categories, expand category
 117                         <b>Tracing</b> and select
 118                         <b>Tracing Project</b> and the click on
 119                         <b>Next &gt;</b>. A second page of the wizard will show. Now enter the a name in the field
 120                         <b>Project Name</b>, select a location if required and the press on
 121                         <b>Finish</b>.
 122                 </p>
 123                 <p>
 124                         <img border="0" src="images/NewTracingProjectPage2.png"/>
 125                 </p>
 126                 <p>A new project will appear in the
 127                         <b>Project Explorer</b> view.
 128                 </p>
 129                 <p>
 130                         <img border="0" src="images/NewProjectExplorer.png"/>
 131                 </p>
 132                 <p>Tracing projects have two sub-folders:
 133                         <b>Traces</b> which holds the individual traces, and
 134                         <b>Experiments</b> which holds sets of traces that we want to correlate.
 135                 </p>
 136                 <h3 id="Importing_Traces_in_a_Project">Importing Traces in a Project</h3>
 137                 <p>The
 138                         <b>Traces</b> folder holds the set of traces available for experiments. To import a trace to the traces folder, select the Traces folder and click the right mouse button. Then select
 139                         <b>Import...</b> menu item in the context-sensitive menu.
 140                 </p>
 141                 <p>
 142                         <img border="0" src="images/ProjectImportTraceAction.png"/>
 143                 </p>
 144                 <p>A new display will show for selecting traces to import. By default, it shows the correct destination directory where the traces will be imported to. Now, specify the location of the traces by entering the path directly in the
 145                         <b>Source Directory</b> or by browsing the file system (click on button browse). Then select the traces to import in the list of files and folders. Optionally, select the
 146                         <b>Trace Type</b> from the drop-down menu, select or deselect the checkboxes for
 147                         <b>Overwrite existing trace without warning</b> and
 148                         <b>Create links into workspace</b>. When all options are configured, click on
 149                         <b>Finish</b>.
 150                 </p>
 151                 <p>Note, that traces of certain types (e.g. LTTng Kernel) are actually a composite of multiple channel traces grouped under a folder. It is the folder that has to be imported.</p>
 152                 <p>
 153                         <img border="0" src="images/ProjectImportTraceDialog.png"/>
 154                 </p>
 155                 <p>Upon successful importing the traces will be stored in the
 156                         <b>Traces</b> folder. If a trace type was selected in the import dialog, then the corresponding icon will be displayed. Linked traces will have a little arrow as decorator on the right bottom corner.
 157                 </p>
 158                 <p>Note that trace type is an extension point of the
 159                         <b>Tracing and Monitoring Framework (TMF)</b>. Depending on the which features are loaded, the list of trace types can vary.
 160                 </p>
 161                 <h3 id="Selecting_a_Trace_Type">Selecting a Trace Type</h3>
 162                 <p>If no trace type was selected a trace type as to be associated to a trace before it can be opened. To select a trace type select the relevant trace and click the right mouse button. In the context-sensitive menu, select
 163                         <b>Select Trace Type...</b> menu item. A sub-menu will show will all available trace type categories. From the relevant category select the required trace type. The examples, below show how to select the
 164                         <b>Common Trace Format</b> types
 165                         <b>LTTng Kernel</b> and
 166                         <b>Generic CTF trace</b>.
 167                 </p>
 168                 <p>
 169                         <img border="0" src="images/SelectLTTngKernelTraceType.png"/>
 170                 </p>
 171                 <p>
 172                         <img border="0" src="images/SelectGenericCTFTraceType.png"/>
 173                 </p>
 174                 <p>After selecting the trace type, the trace icon will be updated with the corresponding trace type icon.</p>
 175                 <p>
 176                         <img border="0" src="images/ExplorerWithAssociatedTraceType.png"/>
 177                 </p>
 178                 <h3 id="Creating_a_Experiment">Creating a Experiment</h3>
 179                 <p>An experiment consists in an arbitrary number of aggregated traces for purpose of correlation. In the degenerate case, an experiment can consist of a single trace. The experiment provides a unified, time-ordered stream of the individual trace events. </p>
 180                 <p>To create an experiment, select the folder
 181                         <b>Experiments</b> and click the right mouse button. Then select
 182                         <b>New...</b>.
 183                 </p>
 184                 <p>
 185                         <img border="0" src="images/NewExperimentAction.png"/>
 186                 </p>
 187                 <p>A new display will open for entering the experiment name. Type the name of the experiment in the text field
 188                         <b>Experiment Name</b> and the click on
 189                         <b>OK</b>.
 190                 </p>
 191                 <p>
 192                         <img border="0" src="images/NewExperimentDialog.png"/>
 193                 </p>
 194                 <h3 id="Selecting_Traces_for_an_Experiment">Selecting Traces for an Experiment</h3>
 195                 <p>After creating an experiment, traces need to be added to the experiment. To select traces for an experiment select the newly create experiment and click the right mouse button. Select
 196                         <b>Select Traces...</b> from the context sensitive menu.
 197                 </p>
 198                 <p>
 199                         <img border="0" src="images/SelectTracesAction.png"/>
 200                 </p>
 201                 <p>A new dialog box will open with a list of available traces. Select the traces to add from the list and then click on
 202                         <b>Finish</b>.
 203                 </p>
 204                 <p>
 205                         <img border="0" src="images/SelectTracesDialog.png"/>
 206                 </p>
 207                 <p>Now the selected traces will be linked to the experiment and will be shown under the
 208                         <b>Experiments</b> folder.
 209                 </p>
 210                 <p>
 211                         <img border="0" src="images/ExplorerWithExperiment.png"/>
 212                 </p>
 213                 <p>Alternatively, traces can be added to an experiment using
 214                         <a href="LTTng.html#Drag_and_Drop">Drag and Drop</a>.
 215                 </p>
 216                 <h3 id="Removing_Traces_from_an_Experiment">Removing Traces from an Experiment</h3>
 217                 <p>To remove one or more traces for an experiment select the trace(s) to remove under the Experiment folder and click the right mouse button. Select
 218                         <b>Remove</b> from the context sensitive menu.
 219                 </p>
 220                 <p>
 221                         <img border="0" src="images/RemoveTracesAction.png"/>
 222                 </p>
 223                 <p>After that the selected trace(s) are removed from the experiment. Note that the traces are still in the
 224                         <b>Traces</b> folder.
 225                 </p>
 226                 <h3 id="Renaming_a_Trace_or_Experiment">Renaming a Trace or Experiment</h3>
 227                 <p>Traces and Experiment can be renamed from the
 228                         <b>Project Explorer</b> view. To rename a trace or experiment select the relevant trace and click the right mouse button. Then select
 229                         <b>Rename...</b> from the context sensitive menu. The trace or experiment needs to be closed in order to do this operation.
 230                 </p>
 231                 <p>
 232                         <img border="0" src="images/RenameTraceAction.png"/>
 233                 </p>
 234                 <p>A new dialog box will show for entering a new name. Enter a new trace or experiment name respectively in the relevant text field and click on
 235                         <b>OK</b>. If the new name already exists the dialog box will show an error and a different name has to be entered.
 236                 </p>
 237                 <p>
 238                         <img border="0" src="images/RenameTraceDialog.png"/>
 239                 </p>
 240                 <p>
 241                         <img border="0" src="images/RenameExperimentDialog.png"/>
 242                 </p>
 243                 <p>After successful renaming the new name will show in the
 244                         <b>Project Explorer</b>. In case of a trace all reference links to that trace will be updated too. Note that linked traces only changes the display name, the underlying trace resource will stay the original name.
 245                 </p>
 246                 <p>Note that all supplementary files will be also handled accordingly (see also
 247                         <a href="LTTng.html#Deleting_Supplementary_Files">Deleting Supplementary Files</a>).
 248                 </p>
 249                 <h3 id="Copying_a_Trace_or_Experiment">Copying a Trace or Experiment</h3>
 250                 <p>To copy a trace or experiment select the relevant trace or experiment in the
 251                         <b>Project Explorer</b> view and click the right mouse button. Then select
 252                         <b>Copy...</b> from the context sensitive menu.
 253                 </p>
 254                 <p>
 255                         <img border="0" src="images/CopyTraceAction.png"/>
 256                 </p>
 257                 <p>A new dialog box will show for entering a new name. Enter a new trace or experiment name respectively in the relevant text field and click on
 258                         <b>OK</b>. If the new name already exists the dialog box will show an error and a different name has to be entered.
 259                 </p>
 260                 <p>
 261                         <img border="0" src="images/CopyTraceDialog.png"/>
 262                 </p>
 263                 <p>
 264                         <img border="0" src="images/CopyExperimentDialog.png"/>
 265                 </p>
 266                 <p>After successful copy operation the new trace or experiment respectively will show in the
 267                         <b>Project Explorer</b>. In case of a linked trace, the copied trace will be a link to the original trace too.
 268                 </p>
 269                 <p>Note that the directory for all supplementary files will be copied, too. (see also
 270                         <a href="LTTng.html#Deleting_Supplementary_Files">Deleting Supplementary Files</a>).
 271                 </p>
 272                 <h3 id="Deleting_a_Trace_or_Experiment">Deleting a Trace or Experiment</h3>
 273                 <p>To delete a trace or experiment select the relevant trace or experiment in the
 274                         <b>Project Explorer</b> view and click the right mouse button. Then select
 275                         <b>Delete...</b> from the context sensitive menu. The trace or experiment needs to be closed in order to do this operation.
 276                 </p>
 277                 <p>
 278                         <img border="0" src="images/DeleteExperimentAction.png"/>
 279                 </p>
 280                 <p>A confirmation dialog box will open. To perform the deletion press
 281                         <b>OK</b> otherwise select
 282                         <b>Cancel</b>.
 283                 </p>
 284                 <p>
 285                         <img border="0" src="images/DeleteExperimentConfirmationDialog.png"/>
 286                 </p>
 287                 <p>After successful operation the selected trace or experiment will be removed from the project. In case of a linked trace only the link will be removed. The actual trace resource remain on the disk. </p>
 288                 <p>Note that the directory for all supplementary files will be deleted, too. (see also
 289                         <a href="LTTng.html#Deleting_Supplementary_Files">Deleting Supplementary Files</a>).
 290                 </p>
 291                 <h3 id="Deleting_Supplementary_Files">Deleting Supplementary Files</h3>
 292                 <p>Supplementary files are by definition trace specific files that accompany a trace. These file could be temporary files, persistent indexes or any other persistent data files created by the LTTng integration in Eclipse during parsing a trace. For the LTTng 2.0 trace viewer a persistent state history of the Linux Kernel is created and is stored under the name
 293                         <b>stateHistory.ht</b>. The statistics for all traces are stored under
 294                         <b>statistics.ht</b>. Other state systems may appear in the same folder as more custom views are added.
 295                 </p>
 296                 <p>All supplementary file are hidden from the user and are handled internally by the TMF. However, there is a possibility to delete the supplementary files so that there are recreated when opening a trace.</p>
 297                 <p>To delete all supplementary files from a single trace, first, make sure the trace is not opened, then select the relevant trace in the
 298                         <b>Project Explorer</b> view and click the right mouse button. Then select the
 299                         <b>Delete Supplementary Files...</b> menu item from the context-sensitive menu.
 300                 </p>
 301                 <p>
 302                         <img border="0" src="images/DeleteSupplementaryFilesAction.png"/>
 303                 </p>
 304                 <p>A new dialog box will open with a list of supplementary files. Select the file(s) to delete from the list and press
 305                         <b>OK</b>.
 306                 </p>
 307                 <p>
 308                         <img border="0" src="images/DeleteSupplementaryFilesDialog.png"/>
 309                 </p>
 310                 <p>To delete all supplementary files from all traces of a experiment, select the relevant experiment in the
 311                         <b>Project Explorer</b> view and click the right mouse button. In the context-sensitive menu select
 312                         <b>Delete Supplementary Files...</b> menu item. The experiment and included traces need to be closed in order to do this operation.
 313                 </p>
 314                 <p>A new dialog box will open with a list of supplementary files. Note that the supplementary files are prefixed with the trace name to indicate the trace they belong to. Select the file(s) to delete from the list and press
 315                         <b>OK</b>.
 316                 </p>
 317                 <p>
 318                         <img border="0" src="images/DeleteExpSupplementaryFilesDialog.png"/>
 319                 </p>
 320                 <h3 id="Opening_a_Trace_or_Experiment">Opening a Trace or Experiment</h3>
 321                 <p>A trace or experiment can be open by double-clicking the left mouse button on the trace or experiment in the
 322                         <b>Project Explorer</b> view. Alternatively, select the trace or experiment in the in the
 323                         <b>Project Explorer</b> view and click the right mouse button. Then select
 324                         <b>Open</b> menu item of the context-sensitive menu.
 325                 </p>
 326                 <p>
 327                         <img border="0" src="images/OpenTraceAction.png"/>
 328                 </p>
 329                 <p>When opening a trace or experiment all currently open view will be filled which are defined for the corresponding trace type. Additionally, an internal index will be created for fast navigation within a trace. For LTTng 2.0 kernel traces a persistent state history will also be build. This state history will be used in different views to display kernel state information.</p>
 330                 <h3 id="Drag_and_Drop">Drag and Drop</h3>
 331                 <p>Traces can be also be imported to a project by dragging from another tracing project and dropping to the project's trace folder. The trace will be copied and the trace type will be set.</p>
 332                 <p>Any resource can be dragged and dropped from a non-tracing project, and any file or folder can be dragged from an external tool, into a tracing project's trace folder. The resource will be copied or imported as a new trace, however the trace type will be unknown and need to be set manually by the user.</p>
 333                 <p>It is also possible to drop a trace, resource, file or folder into an existing experiment. If the item does not already exist as a trace in the project's trace folder, it will first be copied or imported, then the trace will be added to the experiment.</p>
 334                 <h2 id="Events_Editor">Events Editor</h2>
 335                 <p>The Events editor shows the basic trace data elements (events) in a tabular format. The editors can be dragged in the editor area so that several traces may be shown side by side. These traces are synchronized by timestamp.</p>
 336                 <p>
 337                         <img border="0" src="images/LTTng2EventsEditor.png"/>
 338                 </p>
 339                 <p>The header displays the current trace (or experiment) name. </p>
 340                 <p>Being part of the
 341                         <b>Tracing and Monitoring</b> Framework, the default table displays the following fields:
 342                 </p>
 343                 <ul>
 344                         <li>
 345                                 <b>Timestamp</b>: the event timestamp
 346                         </li>
 347                         <li>
 348                                 <b>Source</b>: the source of the event
 349                         </li>
 350                         <li>
 351                                 <b>Type</b>: the event type and localization
 352                         </li>
 353                         <li>
 354                                 <b>Reference</b> the event reference
 355                         </li>
 356                         <li>
 357                                 <b>Content</b>: the raw event content
 358                         </li>
 359                 </ul>
 360                 <p>The first row of the table is the header row a.k.a. the Search and Filter row.</p>
 361                 <p>The highlighted event is the
 362                         <i>current event</i> 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.
 363                 </p>
 364                 <p>
 365                         <img border="0" src="images/LTTng2EventProperties.png"/>
 366                 </p>
 367                 <p>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.</p>
 368                 <h3 id="Searching_and_Filtering">Searching and Filtering</h3>
 369                 <p>Searching and filtering of events in the table can be performed by entering matching conditions in one or multiple columns in the header row (the first row below the column header).</p>
 370                 <p>To toggle between searching and filtering, click on the 'search' (
 371                         <img border="0" src="images/TmfEventSearch.gif"/>) or 'filter' (
 372                         <img border="0" src="images/TmfEventFilter.gif"/>) icon in the header row's left margin, or right-click on the header row and select
 373                         <b>Show Filter Bar</b> or
 374                         <b>Show Search Bar</b> in the context menu.
 375                 </p>
 376                 <p>To apply a matching condition to a specific column, click on the column's header row cell, type in a
 377                         <a href="http://download.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">regular expression</a> and press the
 378                         <b>ENTER</b> key. You can also enter a simple text string and it will be automatically be replaced with a 'contains' regular expression.
 379                 </p>
 380                 <p>When matching conditions are applied to two or more columns, all conditions must be met for the event to match (i.e. 'and' behavior).</p>
 381                 <p>To clear all matching conditions in the header row, press the
 382                         <b>DEL</b> key.
 383                 </p>
 384                 <h4 id="Searching">Searching</h4>
 385                 <p>When a searching condition is applied to the header row, the table will select the next matching event starting from the top currently displayed event. Wrapping will occur if there is no match until the end of the trace.</p>
 386                 <p>All matching events will have a 'search match' icon in their left margin. Non-matching events will be dimmed.</p>
 387                 <p>
 388                         <img border="0" src="images/DefaultTmfEvents-Search.png"/>
 389                 </p>
 390                 <p>Pressing the
 391                         <b>ENTER</b> key will search and select the next matching event. Pressing the
 392                         <b>SHIFT-ENTER</b> key will search and select the previous matching event. Wrapping will occur in both directions.
 393                 </p>
 394                 <p>Press
 395                         <b>ESC</b> to cancel an ongoing search.
 396                 </p>
 397                 <p>Press
 398                         <b>DEL</b> to clear the header row and reset all events to normal.
 399                 </p>
 400                 <h4 id="Filtering">Filtering</h4>
 401                 <p>When a filtering condition is entered in the head row, the table will clear all events and fill itself with matching events as they are found from the beginning of the trace.</p>
 402                 <p>A status row will be displayed before and after the matching events, dynamically showing how many matching events were found and how many events were processed so far. Once the filtering is completed, the status row icon in the left margin will change from a 'stop' to a 'filter' icon.</p>
 403                 <p>
 404                         <img border="0" src="images/DefaultTmfEvents-Filter.png"/>
 405                 </p>
 406                 <p>Press
 407                         <b>ESC</b> to stop an ongoing filtering. In this case the status row icon will remain as a 'stop' icon to indicate that not all events were processed.
 408                 </p>
 409                 <p>Press
 410                         <b>DEL</b> or right-click on the table and select
 411                         <b>Clear Filters</b> from the context menu to clear the header row and remove the filtering. All trace events will be now shown in the table. Note that the currently selected event will remain selected even after the filter is removed.
 412                 </p>
 413                 <p>You can also search on the subset of filtered events by toggling the header row to the Search Bar while a filter is applied. Searching and filtering conditions are independent of each other.</p>
 414                 <h4 id="Bookmarking">Bookmarking</h4>
 415                 <p>Any event of interest can be tagged with a bookmark.</p>
 416                 <p>To add a bookmark, double-click the left margin next to an event, or right-click the margin and select
 417                         <b>Add bookmark...</b>. Alternatively use the
 418                         <b>Edit</b> &gt;
 419                         <b>Add bookmark...</b> menu. Edit the bookmark description as desired and press
 420                         <b>OK</b>.
 421                 </p>
 422                 <p>The bookmark will be displayed in the left margin, and hovering the mouse over the bookmark icon will display the description in a tooltip.</p>
 423                 <p>The bookmark will be added to the
 424                         <b>Bookmarks</b> view. In this view the bookmark description can be edited, and the bookmark can be deleted. Double-clicking the bookmark or selecting
 425                         <b>Go to</b> from its context menu will open the trace or experiment and go directly to the event that was bookmarked.
 426                 </p>
 427                 <p>To remove a bookmark, double-click its icon, select
 428                         <b>Remove Bookmark</b> from the left margin context menu, or select
 429                         <b>Delete</b> from the Bookmarks view.
 430                 </p>
 431                 <p>
 432                         <img border="0" src="images/Bookmarks.png"/>
 433                 </p>
 434                 <h2 id="Histogram_View">Histogram View</h2>
 435                 <p>The Histogram View displays the trace events distribution with respect to time. When streaming a trace, this view is dynamically updated as the events are received.</p>
 436                 <p>
 437                         <img border="0" src="images/HistogramView.png"/>
 438                 </p>
 439                 <p>On the top left, there are two data controls:</p>
 440                 <ul>
 441                         <li>
 442                                 <b>Current Event (sec)</b>: Displays the timestamp of the currently selected event
 443                         </li>
 444                         <li>
 445                                 <b>Window Span (sec)</b>: Displays the current time range window size
 446                         </li>
 447                 </ul>
 448                 <p>Both control can be used to modify their respective value. After validation, the other controls and views will be synchronized and updated accordingly.</p>
 449                 <p>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.</p>
 450                 <p>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.</p>
 451                 <p>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.</p>
 452                 <p>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.</p>
 453                 <p>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.</p>
 454                 <p>In each histogram, the following keys are handled:</p>
 455                 <ul>
 456                         <li>
 457                                 <b>Left</b>: Moves the current event to the previous non-empty bar
 458                         </li>
 459                         <li>
 460                                 <b>Right</b>: Moves the current event to the next non-empty bar
 461                         </li>
 462                         <li>
 463                                 <b>Home</b>: Displays the current event to the first histogram bar
 464                         </li>
 465                         <li>
 466                                 <b>End</b>: Displays the current event to the last non-empty histogram bar
 467                         </li>
 468                 </ul>
 469                 <h2 id="Statistics_View">Statistics View</h2>
 470                 <p>The Statistics View displays the various event counters that are collected when analyzing a trace. The data is organized per trace. To open the Statistics View, select Windows -&gt; Show View -&gt; Other... -&gt; Tracing -&gt; Statistics. A new view will open with the name Statistics. This view shows 3 columns:
 471                         <i>Level</i>
 472                         <i>Events total</i> and
 473                         <i>Events in selected time range</i>. After parsing a trace the view will display the number of events per event type in the second column and in the third, the currently selected time range's event type distribution is shown. The cells where the number of events are printed also contain a colored bar that indicates the percentage of the event count in relation to the total number of events. The statistics is collected for the whole trace. This view is part of the
 474                         <b>Tracing and Monitoring Framework (TMF)</b> and is generic. It will work for any trace type extensions. For the LTTng 2.0 integration the Statistics view will display statistics as shown below.:
 475                 </p>
 476                 <p>
 477                         <img border="0" src="images/LTTng2StatisticsView.png"/>
 478                 </p>
 479                 <p>By default, the statistics use a state system, therefore will load very quickly once the state system is written to the disk as a supplementary file.</p>
 480                 <h2 id="Colors_View">Colors View</h2>
 481                 <p>
 482                         <img border="0" src="images/ColorsView.png"/>
 483                 </p>
 484                 <p>The Colors view allows the user to define a prioritized list of color settings.</p>
 485                 <p>A color setting associates a foreground and background color (used in any events table), and a tick color (used in the Time Chart view), with an event filter.</p>
 486                 <p>In an events table, any event row that matches the event filter of a color setting will be displayed with the specified foreground and background colors. If the event matches multiple filters, the color setting with the highest priority will be used.</p>
 487                 <p>The same principle applies to the event tick colors in the Time Chart view. If a tick represents many events, the tick color of the highest priority matching event will be used.</p>
 488                 <p>Color settings can be inserted, deleted, reordered, imported and exported using the buttons in the Colors view toolbar. Changes to the color settings are applied immediately, and are persisted to disk.</p>
 489                 <h2 id="Filters_View">Filters View</h2>
 490                 <p>
 491                         <img border="0" src="images/FiltersView.png"/>
 492                 </p>
 493                 <p>The Filters view allows the user to define preset filters that can be applied to any events table.</p>
 494                 <p>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
 495                         <b>EVENTTYPE</b>,
 496                         <b>AND</b>,
 497                         <b>OR</b>,
 498                         <b>CONTAINS</b>,
 499                         <b>EQUALS</b>,
 500                         <b>MATCHES</b> or
 501                         <b>COMPARE</b>. Some nodes types have restrictions on their possible children in the tree.
 502                 </p>
 503                 <p>The
 504                         <b>EVENTTYPE</b> 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.
 505                 </p>
 506                 <p>The
 507                         <b>AND</b> node applies the logical
 508                         <i>and</i> condition on all of its children. All children conditions must be true for the filter to match. A
 509                         <i>not</i> operator can be applied to invert the condition.
 510                 </p>
 511                 <p>The
 512                         <b>OR</b> node applies the logical
 513                         <i>or</i> condition on all of its children. At least one children condition must be true for the filter to match. A
 514                         <i>not</i> operator can be applied to invert the condition.
 515                 </p>
 516                 <p>The
 517                         <b>CONTAINS</b> node matches when the specified event
 518                         <i>field</i> value contains the specified
 519                         <i>value</i> string. A
 520                         <i>not</i> operator can be applied to invert the condition. The condition can be case sensitive or insensitive.
 521                 </p>
 522                 <p>The
 523                         <b>EQUALS</b> node matches when the specified event
 524                         <i>field</i> value equals exactly the specified
 525                         <i>value</i> string. A
 526                         <i>not</i> operator can be applied to invert the condition. The condition can be case sensitive or insensitive.
 527                 </p>
 528                 <p>The
 529                         <b>MATCHES</b> node matches when the specified event
 530                         <i>field</i> value matches against the specified
 531                         <i>regular expression</i>. A
 532                         <i>not</i> operator can be applied to invert the condition.
 533                 </p>
 534                 <p>The
 535                         <b>COMPARE</b> node matches when the specified event
 536                         <i>field</i> value compared with the specified
 537                         <i>value</i> gives the specified
 538                         <i>result</i>. The result can be set to
 539                         <i>smaller than</i>,
 540                         <i>equal</i> or
 541                         <i>greater than</i>. The type of comparison can be numerical, alphanumerical or based on time stamp. A
 542                         <i>not</i> operator can be applied to invert the condition.
 543                 </p>
 544                 <p>Filters can be added, deleted, imported and exported using the buttons in the Filters view toolbar. Changes to the preset filters are only applied and persisted to disk when the
 545                         <b>save filters</b> button is pressed.
 546                 </p>
 547                 <p>To apply a saved preset filter in an events table, right-click on the table and select
 548                         <b>Apply preset filter...</b> &gt;
 549                         <i>filter name</i>.
 550                 </p>
 551                 <h2 id="Time_Chart_View">Time Chart View</h2>
 552                 <p>
 553                         <img border="0" src="images/TimeChartView.png"/>
 554                 </p>
 555                 <p>The Time Chart view allows the user to visualize every open trace in a common time chart. Each trace is display in its own row and ticks are display for every punctual event. As the user zooms using the mouse wheel or by right-clicking and dragging in the time scale, more detailed event data is computed from the traces.</p>
 556                 <p>Time synchronization is enabled between the time chart view and other trace viewers such as the events table.</p>
 557                 <p>Color settings defined in the Colors view can be used to change the tick color of events displayed in the Time Chart view.</p>
 558                 <p>When a search is applied in the events table, the ticks corresponding to matching events in the Time Chart view are decorated with a marker below the tick.</p>
 559                 <p>When a bookmark is applied in the events table, the ticks corresponding to the bookmarked event in the Time Chart view is decorated with a bookmark above the tick.</p>
 560                 <p>When a filter is applied in the events table, the non-matching ticks are removed from the Time Chart view.</p>
 561                 <p>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.</p>
 562                 <h2 id="Environment_Variables_View">Environment Variables View</h2>
 563                 <p>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.
 564                         <br/>
 565
 566                         <img border="0" src="images/LTTng2EnvironmentsView.png"/>
 567                         <br/>
 568                         The above picture shows a trace loaded that was collevcted with the
 569                         <b>lttng-modules</b> version
 570                         <b>2</b>.
 571                         <b>0</b>.
 572                         <b>0</b> tracer. It is a
 573                         <b>kernel</b> trace of the
 574                         <b>3.2.0-18-generic</b>
 575                         <b>linux</b> kernel.
 576                 </p>
 577                 <h2 id="Custom_Parser">Custom Parser</h2>
 578                 <p>Custom parser wizards allow the user to define their own parsers for text or XML traces. The user defines how the input should be parsed into internal trace events and identifies the event fields that should be created and displayed. Traces created using a custom parser can be correlated with other built-in traces or traces added by plug-in extension.</p>
 579                 <h3 id="Creating_a_custom_text_parser">Creating a custom text parser</h3>
 580                 <p>The
 581                         <b>New Custom Text Parser</b> wizard can be used to create a custom parser for text logs. It can be launched several ways:
 582                 </p>
 583                 <ul>
 584                         <li>Select
 585                                 <b>File</b> &gt;
 586                                 <b>New</b> &gt;
 587                                 <b>Other...</b> &gt;
 588                                 <b>Tracing</b> &gt;
 589                                 <b>Custom Text Parser</b>
 590                         </li>
 591                         <li>Open the
 592                                 <b>Manage Custom Parsers</b> dialog from the
 593                                 <b>Project Explorer</b> view menu, select the
 594                                 <b>Text</b> radio button and click the
 595                                 <b>New...</b> button
 596                         </li>
 597                 </ul>
 598                 <p>
 599                         <img border="0" src="images/CustomTextParserInput.png"/>
 600                 </p>
 601                 <p>Fill out the first wizard page with the following information:</p>
 602                 <ul>
 603                         <li>
 604                                 <b>Log type:</b> Enter a name for the custom log entries, which is also the name of the custom parser.
 605                         </li>
 606                         <li>
 607                                 <b>Time Stamp format:</b> Enter the date and time pattern that will be used to output the Time Stamp.
 608                                 <br/>
 609                         </li>
 610                 </ul>
 611                 <p>Note: information about date and time patterns can be found here:
 612                         <a href="http://java.sun.com/javase/6/docs/api/java/text/SimpleDateFormat.html">http://java.sun.com/javase/6/docs/api/java/text/SimpleDateFormat.html</a>
 613                 </p>
 614                 <p>Click the
 615                         <b>Add next line</b>,
 616                         <b>Add child line</b> or
 617                         <b>Remove line</b> buttons to create a new line of input or delete it. For each line of input, enter the following information:
 618                 </p>
 619                 <ul>
 620                         <li>
 621                                 <b>Regular expression:</b> Enter a regular expression that should match the input line in the log, using capturing groups to extract the data.
 622                                 <br/>
 623                         </li>
 624                 </ul>
 625                 <p>Note: information about date and time patterns can be found here:
 626                         <a href="http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html">http://java.sun.com/javase/6/docs/api/java/util/regex/Pattern.html</a>
 627                 </p>
 628                 <ul>
 629                         <li>
 630                                 <b>Cardinality:</b> 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.
 631                         </li>
 632                 </ul>
 633                 <p><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.</p>
 634                 <p>Click the
 635                         <b>Add group</b> or
 636                         <b>Remove group</b> buttons to define the data extracted from the capturing groups in the line's regular expression. For each group, enter the following information:
 637                 </p>
 638                 <ul>
 639                         <li>
 640                                 <b>Name combo:</b> Select a name for the extracted data:
 641                                 <ul>
 642                                         <li>
 643                                                 <b>Time Stamp</b>: Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
 644                                         </li>
 645                                         <li>
 646                                                 <b>Message</b>: Select this option to identify the main log entry's message. This is usually a group which could have text of greater length.
 647                                         </li>
 648                                         <li>
 649                                                 <b>Other</b>: Select this option to identify any non-standard data. The name must be entered in the name: text box.
 650                                         </li>
 651                                 </ul>
 652                         </li>
 653                 </ul>
 654                 <ul>
 655                         <li>
 656                                 <b>Action combo:</b> Select the action to be performed on the extracted data:
 657                                 <ul>
 658                                         <li>
 659                                                 <b>Set</b>: Select this option to overwrite the data for the chosen name when there is a match for this group.
 660                                         </li>
 661                                         <li>
 662                                                 <b>Append</b>: Select this option to append to the data with the chosen name, if any, when there is a match for this group.
 663                                         </li>
 664                                         <li>
 665                                                 <b>Append with |</b> : Select this option to append to the data with the chosen name, if any, when there is a match for this group, using a | separator between matches.
 666                                         </li>
 667                                 </ul>
 668                         </li>
 669                 </ul>
 670                 <p>The
 671                         <b>Preview input</b> text box can be used to enter any log data that will be processed against the defined custom parser. When the wizard is invoked from a selected log file resource, this input will be automatically filled with the file contents.
 672                 </p>
 673                 <p>The
 674                         <b>Preview:</b> text field of each capturing group and of the Time Stamp will be filled from the parsed data of the first matching log entry.
 675                 </p>
 676                 <p>In the
 677                         <b>Preview input</b> text box, the matching entries are highlighted with different colors:
 678                 </p>
 679                 <ul>
 680                         <li><code><span style="background:#FFFF00">&nbsp;Yellow&nbsp;</span></code> : indicates uncaptured text in a matching line.</li>
 681                         <li><code><span style="background:#00FF00">&nbsp;Green&nbsp;&nbsp;</span></code> : indicates a captured group in the matching line's regular expression for which a custom parser group is defined. This data will be stored by the custom parser.</li>
 682                         <li><code><span style="background:#FF00FF">&nbsp;Magenta</span></code> : indicates a captured group in the matching line's regular expression for which there is no custom parser group defined. This data will be lost.</li>
 683                         <li><code>&nbsp;White&nbsp;&nbsp;</code> : indicates a non-matching line.</li>
 684                 </ul>
 685                 <p>The first line of a matching entry is highlighted with darker colors.</p>
 686                 <p>By default only the first matching entry will be highlighted. To highlight all matching entries in the preview input data, click the
 687                         <b>Highlight All</b> button. This might take a few seconds to process, depending on the input size.
 688                 </p>
 689                 <p>Click the
 690                         <b>Next</b> button to go to the second page of the wizard.
 691                 </p>
 692                 <p>
 693                         <img border="0" src="images/CustomTextParserOutput.png"/>
 694                 </p>
 695                 <p>On this page, the list of default and custom data is shown, along with a preview of the custom parser log table output.</p>
 696                 <p>The custom data output can be modified by the following options:</p>
 697                 <ul>
 698                         <li>
 699                                 <b>Visibility:</b> Select or unselect the checkbox to display the custom data or hide it.
 700                         </li>
 701                 </ul>
 702                 <ul>
 703                         <li>
 704                                 <b>Column order:</b> Click
 705                                 <b>Move before</b> or
 706                                 <b>Move after</b> to change the display order of custom data.
 707                         </li>
 708                 </ul>
 709                 <p>The table at the bottom of the page shows a preview of the custom parser log table output according to the selected options, using the matching entries of the previous page's
 710                         <b>Preview input</b> log data.
 711                 </p>
 712                 <p>Click the
 713                         <b>Finish</b> button to close the wizard and save the custom parser.
 714                 </p>
 715                 <h3 id="Creating_a_custom_XML_parser">Creating a custom XML parser</h3>
 716                 <p>The
 717                         <b>New Custom XML Parser</b> wizard can be used to create a custom parser for XML logs. It can be launched several ways:
 718                 </p>
 719                 <ul>
 720                         <li>Select
 721                                 <b>File</b> &gt;
 722                                 <b>New</b> &gt;
 723                                 <b>Other...</b> &gt;
 724                                 <b>Tracing</b> &gt;
 725                                 <b>Custom XML Parser</b>
 726                         </li>
 727                         <li>Open the
 728                                 <b>Manage Custom Parsers</b> dialog from the
 729                                 <b>Project Explorer</b> view menu, select the
 730                                 <b>XML</b> radio button and click the
 731                                 <b>New...</b> button
 732                         </li>
 733                 </ul>
 734                 <p>
 735                         <img border="0" src="images/CustomXMLParserInput.png"/>
 736                 </p>
 737                 <p>Fill out the first wizard page with the following information:</p>
 738                 <ul>
 739                         <li>
 740                                 <b>Log type:</b> Enter a name for the custom log entries, which is also the name of the custom parser.
 741                         </li>
 742                         <li>
 743                                 <b>Time Stamp format:</b> Enter the date and time pattern that will be used to output the Time Stamp.
 744                                 <br/>
 745                         </li>
 746                 </ul>
 747                 <p>Note: information about date and time patterns can be found here:
 748                         <a href="http://java.sun.com/javase/6/docs/api/java/text/SimpleDateFormat.html">http://java.sun.com/javase/6/docs/api/java/text/SimpleDateFormat.html</a>
 749                 </p>
 750                 <p>Click the
 751                         <b>Add document element</b> button to create a new document element and enter a name for the root-level document element of the XML file.
 752                 </p>
 753                 <p>Click the
 754                         <b>Add child</b> button to create a new element of input to the document element or any other element. For each element, enter the following information:
 755                 </p>
 756                 <ul>
 757                         <li>
 758                                 <b>Element name:</b> Enter a name for the element that must match an element of the XML file.
 759                         </li>
 760                         <li>
 761                                 <b>Log entry:</b> 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.
 762                         </li>
 763                         <li>
 764                                 <b>Name combo:</b> Select a name for the extracted data:
 765                                 <ul>
 766                                         <li>
 767                                                 <b>Ignore</b>: 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.
 768                                         </li>
 769                                         <li>
 770                                                 <b>Time Stamp</b>: Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
 771                                         </li>
 772                                         <li>
 773                                                 <b>Message</b>: Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
 774                                         </li>
 775                                         <li>
 776                                                 <b>Other</b>: 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.
 777                                         </li>
 778                                 </ul>
 779                         </li>
 780                         <li>
 781                                 <b>Action combo:</b> Select the action to be performed on the extracted data:
 782                                 <ul>
 783                                         <li>
 784                                                 <b>Set</b>: Select this option to overwrite the data for the chosen name when there is a match for this element.
 785                                         </li>
 786                                         <li>
 787                                                 <b>Append</b>: Select this option to append to the data with the chosen name, if any, when there is a match for this element.
 788                                         </li>
 789                                         <li>
 790                                                 <b>Append with |</b> : 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.
 791                                         </li>
 792                                 </ul>
 793                         </li>
 794                 </ul>
 795                 <p>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.</p>
 796                 <p>Click the
 797                         <b>Add attribute</b> button to create a new attribute input from the document element or any other element. For each attribute, enter the following information:
 798                 </p>
 799                 <ul>
 800                         <li>
 801                                 <b>Attribute name:</b> Enter a name for the attribute that must match an attribute of this element in the XML file.
 802                         </li>
 803                         <li>
 804                                 <b>Name combo:</b> Select a name for the extracted data:
 805                                 <ul>
 806                                         <li>
 807                                                 <b>Time Stamp</b>: Select this option to identify the time stamp data. The input's data and time pattern must be entered in the format: text box.
 808                                         </li>
 809                                         <li>
 810                                                 <b>Message</b>: Select this option to identify the main log entry's message. This is usually an input which could have text of greater length.
 811                                         </li>
 812                                         <li>
 813                                                 <b>Other</b>: 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.
 814                                         </li>
 815                                 </ul>
 816                         </li>
 817                         <li>
 818                                 <b>Action combo:</b> Select the action to be performed on the extracted data:
 819                                 <ul>
 820                                         <li>
 821                                                 <b>Set</b>: Select this option to overwrite the data for the chosen name when there is a match for this element.
 822                                         </li>
 823                                         <li>
 824                                                 <b>Append</b>: Select this option to append to the data with the chosen name, if any, when there is a match for this element.
 825                                         </li>
 826                                         <li>
 827                                                 <b>Append with |</b> : 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.
 828                                         </li>
 829                                 </ul>
 830                         </li>
 831                 </ul>
 832                 <p>Note: A log entry can inherited input data from its parent elements if the data is extracted at a higher level.</p>
 833                 <p>Click the
 834                         <b>Feeling lucky</b> button to automatically and recursively create child elements and attributes for the current element, according to the XML element data found in the
 835                         <b>Preview input</b> text box, if any.
 836                 </p>
 837                 <p>Click the
 838                         <b>Remove element</b> or
 839                         <b>Remove attribute</b> buttons to remove the extraction of this input data. Take note that all children elements and attributes are also removed.
 840                 </p>
 841                 <p>The
 842                         <b>Preview input</b> text box can be used to enter any XML log data that will be processed against the defined custom parser. When the wizard is invoked from a selected log file resource, this input will be automatically filled with the file contents.
 843                 </p>
 844                 <p>The
 845                         <b>Preview:</b> text field of each capturing element and attribute and of the Time Stamp will be filled from the parsed data of the first matching log entry. Also, when creating a new child element or attribute, its element or attribute name will be suggested if possible from the preview input data.
 846                 </p>
 847                 <p>Click the
 848                         <b>Next</b> button to go to the second page of the wizard.
 849                 </p>
 850                 <p>
 851                         <img border="0" src="images/CustomXMLParserOutput.png"/>
 852                 </p>
 853                 <p>On this page, the list of default and custom data is shown, along with a preview of the custom parser log table output.</p>
 854                 <p>The custom data output can be modified by the following options:</p>
 855                 <ul>
 856                         <li>
 857                                 <b>Visibility:</b> Select or unselect the checkbox to display the custom data or hide it.
 858                         </li>
 859                         <li>
 860                                 <b>Column order:</b> Click
 861                                 <b>Move before</b> or
 862                                 <b>Move before</b> to change the display order of custom data.
 863                         </li>
 864                 </ul>
 865                 <p>The table at the bottom of the page shows a preview of the custom parser log table output according to the selected options, using the matching entries of the previous page's
 866                         <b>Preview input</b> log data.
 867                 </p>
 868                 <p>Click the
 869                         <b>Finish</b> button to close the wizard and save the custom parser.
 870                 </p>
 871                 <h3 id="Managing_custom_parsers">Managing custom parsers</h3>
 872                 <p>The
 873                         <b>Manage Custom Parsers</b> dialog is used to manage the list of custom parsers used by the tool. To open the dialog:
 874                 </p>
 875                 <ul>
 876                         <li>Select
 877                                 <b>Manage Custom Parsers</b> from the
 878                                 <b>Project Explorer</b> view menu.
 879                         </li>
 880                 </ul>
 881                 <p>
 882                         <img border="0" src="images/ManageCustomParsers.png"/>
 883                 </p>
 884                 <p>The ordered list of currently defined custom parsers for the selected type is displayed on the left side of the dialog.</p>
 885                 <p>To change the type of custom parser to manage, select the
 886                         <b>Text</b> or
 887                         <b>XML</b> radio button.
 888                 </p>
 889                 <p>The following actions can be performed from this dialog:</p>
 890                 <ul>
 891                         <li>New...</li>
 892                 </ul>
 893                 <p>Click the
 894                         <b>New...</b> button to launch the
 895                         <b>New Custom Parser</b> wizard.
 896                 </p>
 897                 <ul>
 898                         <li>Edit...</li>
 899                 </ul>
 900                 <p>Select a custom parser from the list and click the
 901                         <b>Edit...</b> button to launch the
 902                         <b>Edit Custom Parser</b> wizard.
 903                 </p>
 904                 <ul>
 905                         <li>Delete</li>
 906                 </ul>
 907                 <p>Select a custom parser from the list and click the
 908                         <b>Delete</b> button to remove the custom parser.
 909                 </p>
 910                 <ul>
 911                         <li>Import...</li>
 912                 </ul>
 913                 <p>Click the
 914                         <b>Import...</b> button and select a file from the opened file dialog to import all its custom parsers.
 915                 </p>
 916                 <ul>
 917                         <li>Export...</li>
 918                 </ul>
 919                 <p>Select a custom parser from the list, click the
 920                         <b>Export...</b> button and enter or select a file in the opened file dialog to export the custom parser. Note that if an existing file containing custom parsers is selected, the custom parser will be appended to the file.
 921                 </p>
 922                 <h3 id="Opening_a_trace_using_a_custom_parser">Opening a trace using a custom parser</h3>
 923                 <p>Once a custom parser has been created, any
 924                         <a href="LTTng.html#Importing_Traces_in_a_Project">imported trace</a> file can be opened and parsed using it.
 925                 </p>
 926                 <p>To do so:</p>
 927                 <ul>
 928                         <li>Select a trace in the
 929                                 <b>Project Explorer</b> view
 930                         </li>
 931                         <li>Right-click the trace and select
 932                                 <b>Select Trace Type...</b> &gt;
 933                                 <b>Custom Text</b> or
 934                                 <b>Custom XML</b> &gt;
 935                                 <i>parser name</i>
 936                         </li>
 937                         <li>Double-click the trace or right-click it and select
 938                                 <b>Open</b>
 939                         </li>
 940                 </ul>
 941                 <p>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.</p>
 942                 <h2 id="LTTng_Tracer_Control">LTTng Tracer Control</h2>
 943                 <p>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. </p>
 944                 <p>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
 945                         <a href="References.html#References">References</a>.
 946                 </p>
 947                 <h3 id="Control_View">Control View</h3>
 948                 <p>To open the Control View, select '
 949                         <i>Window-&gt;Show View-&gt;Other...-&gt;LTTng-&gt;Control View</i>.
 950                 </p>
 951                 <p>
 952                         <img border="0" src="images/LTTngControlView.png"/>
 953                 </p>
 954                 <h4 id="Creating_a_New_Connection_to_a_Remote_Host">Creating a New Connection to a Remote Host</h4>
 955                 <p>To connect to a remote host, select the
 956                         <b>New Connection</b> button in the Control View.
 957                 </p>
 958                 <p>
 959                         <img border="0" src="images/LTTngControlViewConnect.png"/>
 960                 </p>
 961                 <p>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. </p>
 962                 <p>
 963                         <img border="0" src="images/LTTng2NewConnection.png"/>
 964                 </p>
 965                 <p>To use an existing connection definition, select the relevant entry in the drop-down menu and then select
 966                         <b>Ok</b>.
 967                 </p>
 968                 <p>
 969                         <img border="0" src="images/LTTng2SelectConnection.png"/>
 970                 </p>
 971                 <p>To enter the host information manually select first the button
 972                         <b>Edit connection information</b>. Then the text fields
 973                         <b>Connection Name</b> and
 974                         <b>Host Name</b> will enabled. Enter the relevant information and then select
 975                         <b>Ok</b>.
 976                 </p>
 977                 <p>
 978                         <img border="0" src="images/LTTng2EditConnection.png"/>
 979                 </p>
 980                 <p>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
 981                         <b>Enter Password</b> dialog box and select
 982                         <b>Ok</b>.
 983                 </p>
 984                 <p>The
 985                         <b>Host Name</b> holds the IP address or DNS name of the remote system.
 986                         The
 987                         <b>Connection Name</b> is the alias name to be displayed in the Control View.
 988                 </p>
 989                 <p>
 990                         <img border="0" src="images/LTTng2EnterPassword.png"/>
 991                 </p>
 992                 <p>After pressing
 993                         <b>Ok</b> 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.
 994                 </p>
 995                 <p>
 996                         <img border="0" src="images/LTTng2ControlViewFilled.png"/>
 997                 </p>
 998                 <p>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
 999                         <b>CONNECTED</b> the icon is shown
1000                         <img border="0" src="images/Target_connected.gif"/>, otherwise (states
1001                         <b>CONNECTING</b>,
1002                         <b>DISCONNNECTING</b> or
1003                         <b>DISCONNECTED</b> the icon is
1004                         <img border="0" src="images/Target_disconnected.gif"/>.
1005                 </p>
1006                 <p>Under the host level two folder groups are located. The first one is the
1007                         <b>Provider</b> group. The second one is the
1008                         <b>Sessions</b> group.
1009                 </p>
1010                 <p>Under the
1011                         <b>Provider</b> group all trace providers are displayed. Trace providers are
1012                         <b>Kernel</b> and any user space application that supports UST tracing. Under each provider a corresponding list of events are displayed.
1013                 </p>
1014                 <p>Under the
1015                         <b>Sessions</b> 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
1016                         <b>Kernel</b> and
1017                         <b>UST global</b>. Under each domain the configured channels will be displayed. The last level is under the channels where the configured events are displayed.
1018                 </p>
1019                 <p>Each session can be
1020                         <b>ACTIVE</b> or
1021                         <b>INACTIVE</b>. 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
1022                         <img border="0" src="images/Session_active.gif"/>. The icon for an inactive session is
1023                         <img border="0" src="images/Session_inactive.gif"/>.
1024                 </p>
1025                 <p>Each channel can be
1026                         <b>ENABLED</b> or
1027                         <b>DISABLED</b>. 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
1028                         <img border="0" src="images/Channel.gif"/> and the icon for a disabled channel is
1029                         <img border="0" src="images/Channel_disabled.gif"/>.
1030                 </p>
1031                 <p>Events within a channel can be in state
1032                         <b>ENABLED</b> or
1033                         <b>DISABLED</b>. 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
1034                         <img border="0" src="images/Event_enabled.gif"/> and a disabled event the icon
1035                         <img border="0" src="images/Event_disabled.gif"/>.
1036                 </p>
1037                 <h4 id="Disconnecting_from_a_Remote_Host">Disconnecting from a Remote Host</h4>
1038                 <p>To disconnect from a remote host, select the host in the Control View and press the
1039                         <b>Disconnect</b> button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the
1040                         <b>Disconnect</b> button.
1041                 </p>
1042                 <p>
1043                         <img border="0" src="images/LTTng2ControlViewDisconnect.png"/>
1044                 </p>
1045                 <h4 id="Connecting_to_a_Remote_Host">Connecting to a Remote Host</h4>
1046                 <p>To connect to a remote host, select the host in the Control View and press the
1047                         <b>Connect</b> button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the
1048                         <b>Connect</b> button. This will start the connection process as discribed in
1049                         <a href="LTTng.html#Creating_a_New_Connection_to_a_Remote_Host">Creating a New Connection to a Remote Host</a>.
1050                 </p>
1051                 <p>
1052                         <img border="0" src="images/LTTng2ControlViewConnect.png"/>
1053                 </p>
1054                 <h4 id="Deleting_to_a_Remote_Host_Connection">Deleting to a Remote Host Connection</h4>
1055                 <p>To delete a remote host connection, select the host in the Control View and press the
1056                         <b>Delete</b> button. Alternatively, press the right mouse button. A context-sensitive menu will show. Select the
1057                         <b>Delete</b> button. For that command to be active the connection state has to be
1058                         <b>DISCONNECTED</b> and the trace has to be closed.
1059                 </p>
1060                 <p>
1061                         <img border="0" src="images/LTTng2ControlViewDelete.png"/>
1062                 </p>
1063                 <h4 id="Creating_a_Tracing_Session">Creating a Tracing Session</h4>
1064                 <p>To create a tracing session, select the tree node
1065                         <b>Sessions</b> and press the right mouse button. Then select the
1066                         <b>Create Session...</b> button of the context-sensitive menu.
1067                 </p>
1068                 <p>
1069                         <img border="0" src="images/LTTng2CreateSessionAction.png"/>
1070                 </p>
1071                 <p>A dialog box will open for entering information about the session to be created. </p>
1072                 <p>
1073                         <img border="0" src="images/LTTng2CreateSessionDialog.png"/>
1074                 </p>
1075                 <p>Fill in the
1076                         <b>Session Name</b> and optionally the
1077                         <b>Session Path</b> and press
1078                         <b>Ok</b>. Upon successful operation a new session will be created and added under the tree node
1079                         <b>Sessions</b>.
1080                 </p>
1081                 <h4 id="Enabling_Channels_-_General">Enabling Channels - General</h4>
1082                 <p>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.  </p>
1083                 <h4 id="Enabling_Channels_On_Session_Level">Enabling Channels On Session Level</h4>
1084                 <p>To enable a channel, select the tree node of the relevant session and press the right mouse button. Then select the
1085                         <b>Enable Channel...</b> button of the context-sensitive menu.
1086                 </p>
1087                 <p>
1088                         <img border="0" src="images/LTTng2CreateChannelAction.png"/>
1089                 </p>
1090                 <p>A dialog box will open for entering information about the channel to be created.</p>
1091                 <p>
1092                         <img border="0" src="images/LTTng2CreateChannelDialog.png"/>
1093                 </p>
1094                 <p>By default the domain
1095                         <b>Kernel</b> is selected and the corresponding default values are shown. To create a UST channel, select
1096                         <b>UST</b> under the domain section. To get the default values of UST, then press button
1097                         <b>Default</b>.
1098                 </p>
1099                 <p>If required update the following channel information and then press
1100                         <b>Ok</b>.
1101                 </p>
1102                 <ul>
1103                         <li>
1104                                 <b>Channel Name</b>: The name of the channel.
1105                         </li>
1106                         <li>
1107                                 <b>Number of Sub Buffers</b>: The number of sub-buffers of the channel.
1108                         </li>
1109                         <li>
1110                                 <b>Overwrite Mode</b>: The channel overwrite mode (
1111                                 <b>true</b> or
1112                                 <b>false</b>)
1113                         </li>
1114                         <li>
1115                                 <b>Read Timer Interval</b>: The read timer interval.
1116                         </li>
1117                         <li>
1118                                 <b>Sub Buffer size</b>: The size of the sub-buffers of the channel (in bytes).
1119                         </li>
1120                         <li>
1121                                 <b>Switch Timer Interval</b>: The switch timer interval.
1122                         </li>
1123                 </ul>
1124                 <p>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
1125                         <b>ENABLED</b>.
1126                 </p>
1127                 <h4 id="Enabling_Channels_On_Domain_Level">Enabling Channels On Domain Level</h4>
1128                 <p>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
1129                         <b>Enable Channel...</b> button of the context-sensitive menu.
1130                 </p>
1131                 <p>
1132                         <img border="0" src="images/LTTng2CreateChannelOnDomainAction.png"/>
1133                 </p>
1134                 <p>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.</p>
1135                 <p>
1136                         <img border="0" src="images/LTTng2CreateChannelOnDomainDialog.png"/>
1137                 </p>
1138                 <p>Fill the relevant information and press
1139                         <b>Ok</b>.
1140                 </p>
1141                 <h4 id="Enabling_and_Disabling_Channels">Enabling and Disabling Channels</h4>
1142                 <p>To disable one or more enabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the
1143                         <b>Disable Channel</b> menu item of the context-sensitive menu.
1144                 </p>
1145                 <p>
1146                         <img border="0" src="images/LTTng2DisableChannelAction.png"/>
1147                 </p>
1148                 <p>Upon successful operation, the selected channels will be
1149                         <b>DISABLED</b> and the icons for the channels will be updated.
1150                 </p>
1151                 <p>To enable one or more disabled channels, select the tree nodes of the relevant channels and press the right mouse button. Then select the
1152                         <b>Enable Channel</b> menu item of the context-sensitive menu.
1153                 </p>
1154                 <p>
1155                         <img border="0" src="images/LTTng2EnableChannelAction.png"/>
1156                 </p>
1157                 <p>Upon successful operation, the selected channels will be
1158                         <b>ENABLED</b> and the icons for the channels will be updated.
1159                 </p>
1160                 <h4 id="Enabling_Events_-_General">Enabling Events - General</h4>
1161                 <p>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
1162                         <b>channel0</b> which created, if not already exists, by the LTTng tracer control on the server side.
1163                 </p>
1164                 <h4 id="Enabling_Kernel_Events_On_Session_Level">Enabling Kernel Events On Session Level</h4>
1165                 <p>To enable events, select the tree node of the relevant session and press the right mouse button. Then select the
1166                         <b>Enable Event (default channel)...</b> button of the context-sensitive menu.
1167                 </p>
1168                 <p>
1169                         <img border="0" src="images/LTTng2EventOnSessionAction.png"/>
1170                 </p>
1171                 <p>A dialog box will open for entering information about events to be enabled.</p>
1172                 <p>
1173                         <img border="0" src="images/LTTng2EventOnSessionDialog.png"/>
1174                 </p>
1175                 <p>By default the domain
1176                         <b>Kernel</b> is selected and the kernel specific data sections are created. From this dialog box kernel
1177                         <b>Tracepoint</b> events,
1178                         <b>System calls (Syscall)</b>, a
1179                         <b>Dynamic Probe</b> or a
1180                         <b>Dynamic Function entry/return</b> probe can be enabled. Note that events of one of these types at a time can be enabled.
1181                 </p>
1182                 <p>To enable
1183                         <b>Tracepoint</b> events, first select the corresponding
1184                         <b>Select</b> button, then select either all tracepoins (select
1185                         <b>All</b>) or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press
1186                         <b>Ok</b>.
1187                 </p>
1188                 <p>
1189                         <img border="0" src="images/LTTng2TracepointEventsDialog.png"/>
1190                 </p>
1191                 <p>Upon successful operation, the domain
1192                         <b>Kernel</b> 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
1193                         <b>TRACEPOINT</b> under the channel. The channel and events will be
1194                         <b>ENABLED</b>.
1195                 </p>
1196                 <p>
1197                         <img border="0" src="images/LTTng2EnabledKernelTracepoints.png"/>
1198                 </p>
1199                 <p>To enable all
1200                         <b>Syscalls</b>, select the corresponding
1201                         <b>Select</b> button and press
1202                         <b>Ok</b>.
1203                 </p>
1204                 <p>
1205                         <img border="0" src="images/LTTng2SyscallsDialog.png"/>
1206                 </p>
1207                 <p>Upon successful operation, the event with the name
1208                         <b>syscalls</b> and event type
1209                         <b>SYSCALL</b> will be added under the default channel (channel0). If necessary the domain
1210                         <b>Kernel</b> and the channel
1211                         <b>channel0</b> will be created.
1212                 </p>
1213                 <p>
1214                         <img border="0" src="images/LTTng2EnabledKernelSyscalls.png"/>
1215                 </p>
1216                 <p>To enable a
1217                         <b>Dynamic Probe</b> event, select the corresponding
1218                         <b>Select</b> button, fill the
1219                         <b>Event Name</b> and
1220                         <b>Probe</b> fields and press
1221                         <b>Ok</b>. 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...).
1222                 </p>
1223                 <p>
1224                         <img border="0" src="images/LTTng2ProbeEventDialog.png"/>
1225                 </p>
1226                 <p>Upon successful operation, the dynamic probe event with the given name and event type
1227                         <b>PROBE</b> will be added under the default channel (channel0). If necessary the domain
1228                         <b>Kernel</b> and the channel
1229                         <b>channel0</b> will be created.
1230                 </p>
1231                 <p>
1232                         <img border="0" src="images/LTTng2EnabledKernelProbeEvent.png"/>
1233                 </p>
1234                 <p>To enable a
1235                         <b>Dynamic Function entry/return Probe</b> event, select the corresponding
1236                         <b>Select</b> button, fill the
1237                         <b>Event Name</b> and
1238                         <b>Function</b> fields and press
1239                         <b>Ok</b>. 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...).
1240                 </p>
1241                 <p>
1242                         <img border="0" src="images/LTTng2FunctionEventDialog.png"/>
1243                 </p>
1244                 <p>Upon successful operation, the dynamic function probe event with the given name and event type
1245                         <b>PROBE</b> will be added under the default channel (channel0). If necessary the domain
1246                         <b>Kernel</b> and the channel
1247                         <b>channel0</b> will be created.
1248                 </p>
1249                 <p>
1250                         <img border="0" src="images/LTTng2EnabledFunctionProbeEvent.png"/>
1251                 </p>
1252                 <h4 id="Enabling_UST_Events_On_Session_Level">Enabling UST Events On Session Level</h4>
1253                 <p>For enabling UST events, first open the enable events dialog as described in section
1254                         <a href="LTTng.html#Enabling_Kernel_Events_On_Session_Level">Enabling Kernel Events On Session Level</a> and select domain
1255                         <b>UST</b>.
1256                 </p>
1257                 <p>To enable
1258                         <b>Tracepoint</b> events, first select the corresponding
1259                         <b>Select</b> button, then select either all tracepoins (select
1260                         <b>All</b>) or select selectively one or more tracepoints in the displayed tree of tracepoints and finally press
1261                         <b>Ok</b>.
1262                 </p>
1263                 <p>
1264                         <img border="0" src="images/LTTng2UstTracepointEventsDialog.png"/>
1265                 </p>
1266                 <p>Upon successful operation, the domain
1267                         <b>UST global</b> 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
1268                         <b>ENABLED</b>. Note that for the case that
1269                         <b>All</b> tracepoints were selected the wildcard
1270                         <b>*</b> is used which will be shown in the Control View as below.
1271                 </p>
1272                 <p>
1273                         <img border="0" src="images/LTTng2EnabledAllUstTracepoints.png"/>
1274                 </p>
1275                 <p>For UST it is possible to enable
1276                         <b>Tracepoint</b> events using a wildcard. To enable
1277                         <b>Tracepoint</b> events with a wildcard, select first the corresponding
1278                         <b>Select</b> button, fill the
1279                         <b>Wildcard</b> field and press
1280                         <b>Ok</b>.
1281                 </p>
1282                 <p>
1283                         <img border="0" src="images/LTTng2UstWildcardEventsDialog.png"/>
1284                 </p>
1285                 <p>Upon successful operation, the event with the given wildcard and event type
1286                         <b>TRACEPOINT</b> will be added under the default channel (channel0). If necessary the domain
1287                         <b>UST global</b> and the channel
1288                         <b>channel0</b> will be created.
1289                 </p>
1290                 <p>
1291                         <img border="0" src="images/LTTng2EnabledUstWildcardEvents.png"/>
1292                 </p>
1293                 <p>For UST it is possible to enable
1294                         <b>Tracepoint</b> events using log levels. To enable
1295                         <b>Tracepoint</b> events using log levels, select first the corresponding
1296                         <b>Select</b> button, select a log level from the drop down menu, fill in the relevant information (see below) and press
1297                         <b>Ok</b>.
1298                 </p>
1299                 <ul>
1300                         <li>
1301                                 <b>Event Name</b>: Name to display
1302                         </li>
1303                         <li>
1304                                 <b>loglevel</b>: To specify if a range of log levels (0 to selected log level) shall be configured
1305                         </li>
1306                         <li>
1307                                 <b>loglevel-only</b>: To specify that only the specified log level shall be configured
1308                         </li>
1309                 </ul>
1310                 <p>
1311                         <img border="0" src="images/LTTng2UstLoglevelEventsDialog.png"/>
1312                 </p>
1313                 <p>Upon successful operation, the event with the given event name and event type
1314                         <b>TRACEPOINT</b> will be added under the default channel (channel0). If necessary the domain
1315                         <b>UST global</b> and the channel
1316                         <b>channel0</b> will be created.
1317                 </p>
1318                 <p>
1319                         <img border="0" src="images/LTTng2EnabledUstLoglevelEvents.png"/>
1320                 </p>
1321                 <h4 id="Enabling_Events_On_Domain_Level">Enabling Events On Domain Level</h4>
1322                 <p>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
1323                         <b>Enable Event (default channel)...</b>. A new dialog box will open for providing information about the events to be enabled. Depending on the domain,
1324                         <b>Kernel</b> or
1325                         <b>UST global</b>, the domain specifc fields are shown and the domain selector is preselected and read-only.
1326                 </p>
1327                 <p>
1328                         <img border="0" src="images/LTTng2EventOnDomainAction.png"/>
1329                 </p>
1330                 <p>To enable events for domain
1331                         <b>Kernel</b> follow the instructions in section
1332                         <a href="LTTng.html#Enabling_Kernel_Events_On_Session_Level">Enabling Kernel Events On Session Level</a>, for domain
1333                         <b>UST global</b>
1334                         <a href="LTTng.html#Enabling_UST_Events_On_Session_Level">Enabling UST Events On Session Level</a>.
1335                 </p>
1336                 <p>When enabling events on the domain level, the events will be add to the default channel
1337                         <b>channel0</b>. This channel will be created by on the server side if neccessary.
1338                 </p>
1339                 <h4 id="Enabling_Events_On_Channel_Level">Enabling Events On Channel Level</h4>
1340                 <p>Kernel events can also be enabled on the channel level. If necessary, create a channel as described in sections
1341                         <a href="LTTng.html#Enabling_Channels_On_Session_Level">Creating Channels On Session Level</a> or
1342                         <a href="LTTng.html#Enabling_Channels_On_Domain_Level">Creating Channels On Domain Level</a>.
1343                 </p>
1344                 <p>Then select the relevant channel tree node, click the right mouse button and the select
1345                         <b>Enable Event...</b>. A new dialog box will open for providing information about the events to be enabled. Depending on the domain,
1346                         <b>Kernel</b> or
1347                         <b>UST global</b>, the domain specifc fields are shown and the domain selector is preselected and read-only.
1348                 </p>
1349                 <p>
1350                         <img border="0" src="images/LTTng2EventOnChannelAction.png"/>
1351                 </p>
1352                 <p>To enable events for domain
1353                         <b>Kernel</b> follow the instructions in section
1354                         <a href="LTTng.html#Enabling_Kernel_Events_On_Session_Level">Enabling Kernel Events On Session Level</a>, for domain
1355                         <b>UST global</b>
1356                         <a href="LTTng.html#Enabling_UST_Events_On_Session_Level">Enabling UST Events On Session Level</a>.
1357                 </p>
1358                 <p>When enabling events on the channel level, the events will be add to the selected channel.</p>
1359                 <h4 id="Enabling_and_Disabling_Events">Enabling and Disabling Events</h4>
1360                 <p>To disable one or more enabled events, select the tree nodes of the relevant events and click the right mouse button. Then select
1361                         <b>Disable Event</b> menu item in the context-sensitive menu.
1362                 </p>
1363                 <p>
1364                         <img border="0" src="images/LTTng2DisableEventAction.png"/>
1365                 </p>
1366                 <p>Upon successful operation, the selected events will be
1367                         <b>DISABLED</b> and the icons for these events will be updated.
1368                 </p>
1369                 <p>To enable one or more disabled events, select the tree nodes of the relevant events and press the right mouse button. Then select the
1370                         <b>Enable Event</b> menu item of the context-sensitive menu.
1371                 </p>
1372                 <p>
1373                         <img border="0" src="images/LTTng2EnableEventAction.png"/>
1374                 </p>
1375                 <p>Upon successful operation, the selected events will be
1376                         <b>ENABLED</b> and the icons for these events will be updated.
1377                 </p>
1378                 <p>
1379                         <b>Note</b>: There is currently a limitation for kernel event of type
1380                         <b>SYSCALL</b>. 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.
1381                 </p>
1382                 <h4 id="Enabling_Tracepoint_Events_From_Provider">Enabling Tracepoint Events From Provider</h4>
1383                 <p>It is possible to enable events of type
1384                         <b>Tracepoint</b> 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
1385                         <a href="LTTng.html#Creating_a_Tracing_Session">Creating a Tracing Session</a>. Also, if other than default channel
1386                         <b>channel0</b> is required, create a channel as described in sections
1387                         <a href="LTTng.html#Enabling_Channels_On_Session_Level">Creating Channels On Session Level</a> or
1388                         <a href="LTTng.html#Enabling_Channels_On_Domain_Level">Creating Channels On Domain Level</a>.
1389                 </p>
1390                 <p>To assign tracepoint events to a session and channel, select the events to be enabled under the provider (e.g. provider
1391                         <b>Kernel</b>), click right mouse button and then select
1392                         <b>Enable Event...</b> menu item from the context sensitive menu.
1393                 </p>
1394                 <p>
1395                         <img border="0" src="images/LTTng2AssignEventAction.png"/>
1396                 </p>
1397                 <p>A new display will open for defining the session and channel.  </p>
1398                 <p>
1399                         <img border="0" src="images/LTTng2AssignEventDialog.png"/>
1400                 </p>
1401                 <p>Select a session from the
1402                         <b>Session List</b> drop-down menu, a channel from the
1403                         <b>Channel List</b> drop-down menu and the press
1404                         <b>Ok</b>. 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
1405                         <b>channel0</b> will be created for corresponding session. The newly added events will be
1406                         <b>ENABLED</b>.
1407                 </p>
1408                 <p>
1409                         <img border="0" src="images/LTTng2AssignedEvents.png"/>
1410                 </p>
1411                 <h4 id="Adding_Contexts_to_Channels_and_Events_of_a_Domain">Adding Contexts to Channels and Events of a Domain</h4>
1412                 <p>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
1413                         <b>Kernel</b>) and select the menu item
1414                         <b>Add Context...</b> from the context-sensitive menu.
1415                 </p>
1416                 <p>
1417                         <img border="0" src="images/LTTng2AddContextOnDomainAction.png"/>
1418                 </p>
1419                 <p>A new display will open for selecting one or more contexts to add.</p>
1420                 <p>
1421                         <img border="0" src="images/LTTng2AddContextDialog.png"/>
1422                 </p>
1423                 <p>The tree shows all available context that can be added. Select one or more context and the press
1424                         <b>Ok</b>. Upon successful operation, the selected context will be added to all channels and their events of the selected domain.
1425                 </p>
1426                 <p>
1427                         <b>Note</b>: The LTTng UST tracer only supports  contexts
1428                         <b>procname</b>,
1429                         <b>pthread_id</b>,
1430                         <b>vpid</b>
1431                         <b>vtid</b>. Adding any other contexts in the UST domina will fail.
1432                 </p>
1433                 <h4 id="Adding_Contexts_to_All_Events_of_a_Channel">Adding Contexts to All Events of a Channel</h4>
1434                 <p>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
1435                         <b>Add Context...</b> from the context-sensitive menu.
1436                 </p>
1437                 <p>
1438                         <img border="0" src="images/LTTng2AddContextOnChannelAction.png"/>
1439                 </p>
1440                 <p>A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter
1441                         <a href="LTTng.html#Adding_Contexts_to_Channels_and_Events_of_a_Domain">Adding Contexts to Channels and Events of a Domain</a>. Upon successful operation, the selected context will be added to all channels and their events of the selected domain.
1442                         <b>Note</b> 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.
1443                 </p>
1444                 <h4 id="Adding_Contexts_to_a_Event_of_a_Specific_Channel">Adding Contexts to a Event of a Specific Channel</h4>
1445                 <p>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
1446                         <b>Add Context...</b> from the context-sensitive menu.
1447                 </p>
1448                 <p>
1449                         <img border="0" src="images/LTTng2AddContextToEventsAction.png"/>
1450                 </p>
1451                 <p>A new display will open for selecting one or more contexts to add. Select one or more contexts as described in chapter
1452                         <a href="LTTng.html#Adding_Contexts_to_Channels_and_Events_of_a_Domain">Adding Contexts to Channels and Events of a Domain</a>. Upon successful operation, the selected context will be added to the selected event.
1453                 </p>
1454                 <h4 id="Start_Tracing">Start Tracing</h4>
1455                 <p>To start tracing, select one or more sessions to start in the Control View and press the
1456                         <b>Start</b> button. Alternatively, press the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the
1457                         <b>Start</b> menu item.
1458                 </p>
1459                 <p>
1460                         <img border="0" src="images/LTTng2StartTracingAction.png"/>
1461                 </p>
1462                 <p>Upon successful operation, the tracing session will be
1463                         <b>ACTIVE</b> and the icon of the session will be updated.
1464                 </p>
1465                 <h4 id="Stop_Tracing">Stop Tracing</h4>
1466                 <p>To stop tracing, select one or more sessions to stop in the Control View and press the
1467                         <b>Stop</b> button. Alternatively, click the right mouse button on the session tree nodes. A context-sensitive menu will show. Then select the
1468                         <b>Stop</b> menu item.
1469                 </p>
1470                 <p>
1471                         <img border="0" src="images/LTTng2StopTracingAction.png"/>
1472                 </p>
1473                 <p>Upon successful operation, the tracing session will be
1474                         <b>INACTIVE</b> and the icon of the session will be updated.
1475                 </p>
1476                 <h4 id="Destroying_a_Tracing_Session">Destroying a Tracing Session</h4>
1477                 <p>To destroy a tracing session, select one or more sessions to destroy in the Control View and press the
1478                         <b>Destroy</b> button. Alternatively, click the right mouse button on the session tree node. A context-sensitive menu will show. Then select the
1479                         <b>Destroy...</b> menu item. Note that the session has to be
1480                         <b>INACTIVE</b> for this operation.
1481                 </p>
1482                 <p>
1483                         <img border="0" src="images/LTTng2DestroySessionAction.png"/>
1484                 </p>
1485                 <p>A confirmation dialog box will open. Click on
1486                         <b>Ok</b> to destroy the session otherwise click on
1487                         <b>Cancel</b>.
1488                 </p>
1489                 <p>
1490                         <img border="0" src="images/LTTng2DestroyConfirmationDialog.png"/>
1491                 </p>
1492                 <p>Upon successful operation, the tracing session will be destroyed and removed from the tree.</p>
1493                 <h4 id="Refreshing_the_Node_Information">Refreshing the Node Information</h4>
1494                 <p>To refresh the remote host information, select any node in the tree of the Control View and press the
1495                         <b>Refresh</b> button. Alternatively, click the right mouse button on any tree node. A context-sensitive menu will show. Then select the
1496                         <b>Refresh</b> menu item.
1497                 </p>
1498                 <p>
1499                         <img border="0" src="images/LTTng2RefreshAction.png"/>
1500                 </p>
1501                 <p>Upon successful operation, the tree in the Control View will be refreshed with the remote host configuration.</p>
1502                 <h4 id="Quantifing_LTTng_overhead_.28Calibrate.29">Quantifing LTTng overhead (Calibrate)</h4>
1503                 <p>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
1504                         instrumentation (kretprobes). To run the calibrate command, select the a domain (e.g.
1505                         <b>Kernel</b>), click the right mouse button on the domain tree node. A context-sensitive menu will show. Select the
1506                         <b>Calibrate</b> menu item.
1507                 </p>
1508                 <p>
1509                         <img border="0" src="images/LTTng2CalibrateAction.png"/>
1510                 </p>
1511                 <p>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.</p>
1512                 <h4 id="Importing_Session_Traces_to_a_Tracing_Project">Importing Session Traces to a Tracing Project</h4>
1513                 <p>To import traces from a tracing session, select the relevant session and click on the
1514                         <b>Import</b> Button. Alternatively, click the right mouse button on the session tree node and select the menu item
1515                         <b>Import...</b> from the context-sensitive menu.
1516                 </p>
1517                 <p>
1518                         <img border="0" src="images/LTTng2ImportAction.png"/>
1519                 </p>
1520                 <p>A new display will open for selecting the traces to import.</p>
1521                 <p>
1522                         <img border="0" src="images/LTTng2ImportDialog.png"/>
1523                 </p>
1524                 <p>Select the trace to be imported by selecting the relevant traces in the tree viewer, select a tracing project from the
1525                         <b>Available Projects</b> combo box and select the Overwrite button (
1526                         <b>Overwrite existing trace without warning</b>) if required. Then press button
1527                         <b>Ok</b>. Upon successful import operation the the selected traces will be stored in the
1528                         <b>Traces</b> directory of the specified tracing project. From the
1529                         <b>Project Explorer</b> view, the trace can be analyzed further.
1530                 </p>
1531                 <p>
1532                         <b>Note</b>: If the overwrite button (
1533                         <b>Overwrite existing trace without warning</b>) 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.
1534                 </p>
1535                 <p>
1536                         <img border="0" src="images/LTTng2ImportOverwriteConfirmationDialog.png"/>
1537                 </p>
1538                 <p>To Overwrite select the
1539                         <b>Overwrite</b> Button and press
1540                         <b>Ok</b>.
1541                 </p>
1542                 <p>If the existing trace should not be overwritten select, then select the
1543                         <b>Rename</b> option of the confirmation dialog box above, enter a new name and then press
1544                         <b>Ok</b>.
1545                 </p>
1546                 <p>
1547                         <img border="0" src="images/LTTng2ImportRenameDialog.png"/>
1548                 </p>
1549                 <h3 id="Properties_View">Properties View</h3>
1550                 <p>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:</p>
1551                 <p>
1552                         <img border="0" src="images/LTTng2PropertyView.png"/>
1553                 </p>
1554                 <p>
1555                         <b>List of properties</b>:
1556                 </p>
1557                 <ul>
1558                         <li>
1559                                 <b>Host</b> Properties
1560                                 <ul>
1561                                         <li>
1562                                                 <b>Connection Name</b>: The alias name to be displayed in the Control View.
1563                                         </li>
1564                                         <li>
1565                                                 <b>Host Name</b>: The IP address or DNS name of the remote system.
1566                                         </li>
1567                                         <li>
1568                                                 <b>State</b>: The state of the connection (
1569                                                 <b>CONNECTED</b>,
1570                                                 <b>CONNECTING</b>,
1571                                                 <b>DISCONNNECTING</b> or
1572                                                 <b>DISCONNECTED</b>).
1573                                         </li>
1574                                 </ul>
1575                         </li>
1576                         <li>
1577                                 <b>Kernel Provider</b> Properties
1578                                 <ul>
1579                                         <li>
1580                                                 <b>Provider Name</b>: The name of the provider.
1581                                         </li>
1582                                 </ul>
1583                         </li>
1584                         <li>
1585                                 <b>UST Provider</b> Properties
1586                                 <ul>
1587                                         <li>
1588                                                 <b>Provider Name</b>: The name of the provider.
1589                                         </li>
1590                                         <li>
1591                                                 <b>Process ID</b>: The process ID of the provider.
1592                                         </li>
1593                                 </ul>
1594                         </li>
1595                         <li>
1596                                 <b>Event</b> Properties (Provider)
1597                                 <ul>
1598                                         <li>
1599                                                 <b>Event Name</b>: The name of the event.
1600                                         </li>
1601                                         <li>
1602                                                 <b>Event Type</b>: The event type (
1603                                                 <b>TRACEPOINT</b> only).
1604                                         </li>
1605                                         <li>
1606                                                 <b>Log Level</b>: The log level of the event.
1607                                         </li>
1608                                 </ul>
1609                         </li>
1610                         <li>
1611                                 <b>Session</b> Properties
1612                                 <ul>
1613                                         <li>
1614                                                 <b>Session Name</b>: The name of the Session.
1615                                         </li>
1616                                         <li>
1617                                                 <b>Session Path</b>: The path on the remote host where the traces will be stored.
1618                                         </li>
1619                                         <li>
1620                                                 <b>State</b>: The state of the session (
1621                                                 <b>ACTIVE</b> or
1622                                                 <b>INACTIVE</b>)
1623                                         </li>
1624                                 </ul>
1625                         </li>
1626                         <li>
1627                                 <b>Domain</b> Properties
1628                                 <ul>
1629                                         <li>
1630                                                 <b>Domain Name</b>: The name of the domain.
1631                                         </li>
1632                                 </ul>
1633                         </li>
1634                         <li>
1635                                 <b>Channel</b> Properties
1636                                 <ul>
1637                                         <li>
1638                                                 <b>Channel Name</b>: The name of the channel.
1639                                         </li>
1640                                         <li>
1641                                                 <b>Number of Sub Buffers</b>: The number of sub-buffers of the channel.
1642                                         </li>
1643                                         <li>
1644                                                 <b>Output type</b>: The output type for the trace (e.g.
1645                                                 <i>splice()</i> or
1646                                                 <i>mmap()</i>)
1647                                         </li>
1648                                         <li>
1649                                                 <b>Overwrite Mode</b>: The channel overwrite mode (
1650                                                 <b>true</b> for overwrite mode,
1651                                                 <b>false</b> for discard)
1652                                         </li>
1653                                         <li>
1654                                                 <b>Read Timer Interval</b>: The read timer interval.
1655                                         </li>
1656                                         <li>
1657                                                 <b>State</b>: The channel state (
1658                                                 <b>ENABLED</b> or
1659                                                 <b>DISABLED</b>)
1660                                         </li>
1661                                         <li>
1662                                                 <b>Sub Buffer size</b>: The size of the sub-buffers of the channel (in bytes).
1663                                         </li>
1664                                         <li>
1665                                                 <b>Switch Timer Interval</b>: The switch timer interval.
1666                                         </li>
1667                                 </ul>
1668                         </li>
1669                         <li>
1670                                 <b>Event</b> Properties (Channel)
1671                                 <ul>
1672                                         <li>
1673                                                 <b>Event Name</b>: The name of the event.
1674                                         </li>
1675                                         <li>
1676                                                 <b>Event Type</b>: The event type (
1677                                                 <b>TRACEPOINT</b>,
1678                                                 <b>SYSCALL</b> or
1679                                                 <b>PROBE</b>)..
1680                                         </li>
1681                                         <li>
1682                                                 <b>Log Level</b>: The log level of the event.
1683                                         </li>
1684                                         <li>
1685                                                 <b>State</b>: The Event state (
1686                                                 <b>ENABLED</b> or
1687                                                 <b>DISABLED</b>)
1688                                         </li>
1689                                 </ul>
1690                         </li>
1691                 </ul>
1692                 <h3 id="LTTng_Tracer_Control_Preferences">LTTng Tracer Control Preferences</h3>
1693                 <p>Serveral LTTng 2.0 tracer control preferences exists which can be configured. To configure these preferences, select
1694                         <b>Window-&gt;Preferences</b> from the top level menu. The preference display will open. Then select
1695                         <b>Tracing-&gt;LTTng Tracer Control Preferences</b>. 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.
1696                 </p>
1697                 <p>
1698                         <img border="0" src="images/LTTng2Preferences.png"/>
1699                 </p>
1700                 <p>To change the tracing group of the user which will be specified on each command line, enter the new group name in the
1701                         <b>Tracing Group</b> text field and click ok. The default tracing group is
1702                         <b>tracing</b> and can be restored by pressing the
1703                         <b>Restore Defaults</b> button.
1704                 </p>
1705                 <p>
1706                         <img border="0" src="images/LTTng2PreferencesGroup.png"/>
1707                 </p>
1708                 <p>To configure logging of trace control commands and the corresponding command result to a file, selected the button
1709                         <b>Logging</b>. To append to an existing log file, select the
1710                         <b>Append</b> button. Deselect the
1711                         <b>Append</b> button to overwrite any existing log file. It's possible to specify a verbose level. There are 3 levels with inceasing verbosity from
1712                         <b>Level 1</b> to
1713                         <b>Level 3</b>. To change the verbosity level, select the relevant level or select
1714                         <b>None</b>. If
1715                         <b>None</b> is selected only commands and command results are logged. Then press on button
1716                         <b>Ok</b>. The log file will be stored in the users home directory with the name
1717                         <i>lttng_tracer_control.log</i>. The name and location cannot be changed. To reset to default preferences, click on the button
1718                         <b>Restore Defaults</b>.
1719                 </p>
1720                 <p>
1721                         <img border="0" src="images/LTTng2PreferencesLogging.png"/>
1722                 </p><hr/>
1723                 <table class="navigation" style="width: 100%;" border="0" summary="navigation">
1724                         <tr>
1725                                 <td style="width: 20%" align="left">
1726                                         <a href="Installation.html" title="Installation">
1727                                                 <img alt="Previous" border="0" src="images/prev.gif"/>
1728                                         </a>
1729                                 </td>
1730                                 <td style="width: 60%" align="center">
1731                                         <a href="User-Guide.html" title="LTTng Plug-in User Guide">
1732                                                 <img alt="LTTng Plug-in User Guide" border="0" src="images/home.gif"/>
1733                                         </a>
1734                                 </td>
1735                                 <td style="width: 20%" align="right">
1736                                         <a href="LTTng-Kernel-Analysis.html" title="LTTng Kernel Analysis">
1737                                                 <img alt="Next" border="0" src="images/next.gif"/>
1738                                         </a>
1739                                 </td>
1740                         </tr>
1741                         <tr>
1742                                 <td style="width: 20%" align="left" valign="top">Installation</td>
1743                                 <td style="width: 60%" align="center"></td>
1744                                 <td style="width: 20%" align="right" valign="top">LTTng Kernel Analysis</td>
1745                         </tr>
1746                 </table>
1747         </body>
1748 </html>