ltt/branches/poly/QUICKSTART

   1
   2 QUICKSTART
   3
   4 How to use LTTng and LTTV in a few lines :
   5
   6 This document is made of four parts : The first one explains how to install
   7 LTTng and LTTV from Debian and RPM binary packages, the second one explains how
   8 to install LTTng and LTTV from sources and the third one describes the steps
   9 to follow to trace a system and view it. The fourth and last part explains
  10 briefly how to add a new trace point to the kernel.
  11
  12 What you will typically want is to read sections 1 and 3 : install LTTng from
  13 binary packages and use it. If there are no packages ready for your system, you
  14 will have to install from sources (section 2) instead.
  15
  16 These operations are made for installing the LTTng 0.5.X tracer on a
  17 linux 2.6.X kernel. You will also find instructions for installation of
  18 LTTV 0.8.x : the Linux Trace Toolkit Viewer.
  19
  20 To see the list of compatibilities between LTTng, ltt-control, LTTV, genevent
  21 and lttng-modules, please refer to :
  22 http://ltt.polymtl.ca > LTTng+LTTV versions compatibility
  23
  24
  25
  26 The following lttng patch is necessary to have the tracing hooks in the kernel.
  27 The following ltt-control module controls the tracing.
  28
  29 Required programs and librairies are assumed to be automatically installed in an
  30 installation with Debian or RPM packages. In the case of an installation from
  31 sources, the dependencies are listed.
  32
  33
  34 ** Current development status **
  35
  36 LTTng :
  37 supported architectures :
  38 Intel Pentium (UP/SMP) with TSC
  39
  40 LTTV :
  41 supported architectures :
  42 Intel i386 and better
  43 Intel 64 bits
  44 PowerPC
  45
  46
  47
  48 Author : Mathieu Desnoyers, September 2005
  49 Last update : February 10, 2006
  50
  51
  52 ***********************************************************
  53 ** Section 1 * Installation from Debian or RPM packages  **
  54 ***********************************************************
  55
  56 ** NOTE : RPM and debian packages are only made once a version has been
  57    thoroughly tested. If they do not exist at the moment, please install from
  58          sources (see section 2 below). To see the list of compatibilities between
  59          LTTng, ltt-control, LTTV, genevent and lttng-modules, please refer to
  60          http://ltt.polymtl.ca > LTTng+LTTV versions compatibility
  61
  62
  63 * Install from RPM packages on Fedora Core 4 :
  64
  65 Get LTTV RPM from :
  66
  67 http://ltt.polymtl.ca/packages/fedora/RPMS
  68
  69 LTTV RPM are ready.
  70
  71 LTTng kernel and lttng-modules RPM are available for some architectures (i586,
  72 i686). Feel free to help fix the spec files to have correct lttng-modules RPM
  73 package.
  74
  75
  76 * Install from Deb packages on Debian :
  77
  78 You can use the ltt.polymtl.ca apt source to get LTTV for Debian :
  79
  80 Add the following two sources to your /etc/apt/sources.list :
  81
  82 deb http://ltt.polymtl.ca/packages/debian experimental main
  83 deb-src http://ltt.polymtl.ca/packages/debian experimental main
  84
  85
  86 * Install from precompiled binary packages (LTTV compiled only for i386, and
  87   LTTng only for i686 smp), perform the following :
  88
  89 su -
  90 apt-get update
  91 apt-get install lttv lttv-doc
  92 apt-get install kernel-image-2.6.12-rc4-mm2-lttng-0.4.2
  93 apt-get install lttng-modules-modules-2.6.12-rc4-mm2-lttng-0.4.2
  94   * note : the packages are signed by myself. I am not considered a trusted
  95     Debian source yet, so warnings are normal.
  96
  97 Then, follow the section "Editing the system wide configuration" in section 2.
  98
  99 * Create custom LTTV Debian packages
 100
 101 Binary packages are only available for i386. If you want to create your own LTTV
 102 packages for other platforms, do :
 103
 104 su -
 105 cd /usr/src
 106 apt-get source lttv
 107 cd lttv-0.6.9
 108 dpkg-buildpackage -rfakeroot
 109
 110 You should then have your LTTV .deb files created for your architecture.
 111
 112 * Create custom LTTng packages
 113
 114 For building LTTng Debian packages :
 115
 116 su -
 117 apt-get install kernel-source-2.6.12-rc4-mm2-lttng-0.4.2
 118 cd /usr/src
 119 bzip2 -cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2.tar.bz2 | tar xvof -
 120 cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2
 121 make menuconfig (or xconfig or config) (customize your configuration)
 122 make-kpkg kernel_image
 123
 124 You will then see your freshly created .deb in /usr/src. Install it with
 125 dpkg -i /usr/src/(image-name).deb
 126
 127 You will also need to create a package for the lttng-modules :
 128
 129 su -
 130 cd /usr/src
 131 apt-get source lttng-modules
 132 cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2
 133 make-kpkg --added_modules /usr/src/lttng-modules-0.3 modules_image
 134
 135 You will then see your freshly created .deb in /usr/src. Install it with
 136 dpkg -i /usr/src/lttng-modules-modules-(your version).deb
 137
 138
 139 Then, follow the section "Editing the system wide configuration" in section 2.
 140
 141
 142 ***********************************************************
 143 ** Section 2 * Installation from sources                 **
 144 ***********************************************************
 145
 146 * Prerequisites
 147
 148 Tools needed to follow the package download steps :
 149
 150 o wget
 151 o bzip2
 152 o gzip
 153 o tar
 154
 155 You have to install the standard development librairies and programs necessary
 156 to compile a kernel :
 157
 158 (from Documentation/Changes in the Linux kernel tree)
 159 o  Gnu C                  2.95.3                  # gcc --version
 160 o  Gnu make               3.79.1                  # make --version
 161 o  binutils               2.12                    # ld -v
 162 o  util-linux             2.10o                   # fdformat --version
 163 o  module-init-tools      0.9.10                  # depmod -V
 164
 165 You might also want to have libncurses5 to have the text mode kernel
 166 configuration menu, but there are alternatives.
 167
 168 Prerequisites for LTTV 0.x.x installation are :
 169
 170 gcc 3.2 or better
 171 gtk 2.4 or better development libraries
 172   (Debian : libgtk2.0, libgtk2.0-dev)
 173   (Fedora : gtk2, gtk2-devel)
 174   note : For Fedora users : this might require at least core 3 from Fedora,
 175   or you might have to compile your own GTK2 library.
 176 glib 2.4 or better development libraries
 177   (Debian : libglib2.0-0, libglib2.0-dev)
 178   (Fedora : glib2, glib2-devel)
 179 libpopt development libraries
 180   (Debian : libpopt0, libpopt-dev)
 181   (Fedora : popt)
 182 libpango development libraries
 183   (Debian : libpango1.0, libpango1.0-dev)
 184   (Fedora : pango, pango-devel)
 185 libc6 development librairies
 186   (Debian : libc6, libc6-dev)
 187   (Fedora : glibc, glibc)
 188
 189
 190 * Getting the LTTng packages
 191
 192 su -
 193 mkdir /usr/src/lttng
 194 cd /usr/src/lttng
 195 (see http://ltt.polymtl.ca/lttng for package listing)
 196 wget http://ltt.polymtl.ca/lttng/lttng-modules-0.5.tar.bz2
 197 wget http://ltt.polymtl.ca/lttng/patch-2.6.15-lttng-0.x.xx.tar.bz2
 198 bzip2 -cd lttng-modules-0.x.tar.bz2 | tar xvof -
 199 bzip2 -cd patch-2.6.15-lttng-0.x.xx.tar.bz2 | tar xvof -
 200
 201
 202 * Getting LTTng kernel sources
 203
 204 su -
 205 cd /usr/src
 206 wget http://kernel.org/pub/linux/kernel/v2.6/testing/linux-2.6.15.tar.bz2
 207 bzip2 -cd linux-2.6.15.tar.bz2 | tar xvof -
 208 cd linux-2.6.15
 209 cat /usr/src/lttng/patch-2.6.15-lttng-0.x.xx* | patch -p1
 210 cd ..
 211 mv linux-2.6.15 linux-2.6.15-lttng-0.x.xx
 212
 213
 214 * Installing a LTTng kernel
 215
 216 su -
 217 cd /usr/src/linux-2.6.15-lttng-0.x.xx
 218 make menuconfig (or make xconfig or make config)
 219     Select the < Help > button if you are not familiar with kernel
 220     configuration.
 221     Items preceded by [*] means they has to be built into the kernel.
 222     Items preceded by [M] means they has to be built as modules.
 223     Items preceded by [ ] means they should be removed.
 224   go to the "Instrumentation Support" section
 225     Select the following options :
 226     [*] Linux Trace Toolkit Instrumentation Support
 227     <M> or <*> Linux Trace Toolkit Tracer
 228         It makes no difference for the rest of the procedure whether the Tracer
 229         is compiled built-in or as a module.
 230     activate :
 231        [*] Align Linux Trace Toolkit Traces
 232        [*] Allow tracing from userspace
 233     your choice (see < Help >) :
 234        [ ] Activate Linux Trace Toolkit Heartbeat Timer
 235                 You may or may not activate instrumentation per facility. They are all
 236                 selected for logging by default. It can be used as a compile time filter to
 237                 enable/disable logging of events. It is useful to discard events with a
 238                 minimal impact on the system and especially useful for now, as the dynamic
 239                 filter has not been implemented yet.
 240     Select <Exit>
 241   Select <Exit>
 242   Select <Yes>
 243 make
 244 make modules_install
 245 make install
 246
 247 reboot
 248
 249   Select the Linux 2.6.15-lttng-0.x.xx kernel in your boot loader.
 250
 251
 252 * Install the ltt-modules
 253
 254 su -
 255 cd /usr/src/lttng/lttng-modules-0.xx
 256 KERNELDIR=/usr/src/linux-2.6.15-lttng-0.x.xx make
 257 KERNELDIR=/usr/src/linux-2.6.15-lttng-0.x.xx make modules_install
 258
 259
 260 * Editing the system wide configuration
 261
 262 You must activate relayfs and specify a mount point. This is typically done in
 263 fstab such that it happens at boot time.
 264
 265 If you have never used RelayFS before, these operation would do this for you :
 266
 267 mkdir /mnt/relayfs
 268 cp /etc/fstab /etc/fstab.lttng.bkp
 269 echo "relayfs         /mnt/relayfs    relayfs rw              0       0"  >> /etc/fstab
 270
 271 then, rebooting or issuing the following command will activate relayfs :
 272
 273 mount /mnt/relayfs
 274
 275 You need to load the ltt-control module to be able to control tracing from user
 276 space. This is done by issuing the command :
 277
 278 modprobe ltt-control
 279
 280 If you want to have complete information about the kernel state (including all
 281 the process names), you need to load the ltt-statedump module. This is done by
 282 issuing the command :
 283
 284 modprobe ltt-statedump
 285
 286 You can automate at boot time loading the ltt-control module by :
 287
 288 echo ltt-control >> /etc/modules
 289 echo ltt-statedump >> /etc/modules
 290
 291
 292 * Getting and installing the ltt-control package (on the traced machine)
 293
 294 su -
 295 cd /usr/src
 296 wget http://ltt.polymtl.ca/lttng/ltt-control-0.x-xxxx2006.tar.gz
 297 gzip -cd ltt-control-0.x-xxxx2006.tar.gz | tar xvof -
 298 cd ltt-control-0.x-xxxx2006
 299 (refer to README to see the development libraries that must be installed on you
 300 system)
 301 ./configure
 302 make
 303 make install
 304
 305
 306 * Getting and installing the LTTV package (on the visualisation machine, same or
 307   different from the visualisation machine)
 308
 309 su -
 310 cd /usr/src
 311 wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.x.xx-xxxx2006.tar.gz
 312 gzip -cd LinuxTraceToolkitViewer-0.x.xx-xxxx2006.tar.gz | tar xvof -
 313 cd LinuxTraceToolkitViewer-0.x.xx-xxxx2006
 314 (refer to README to see the development libraries that must be installed on you
 315 system)
 316 ./configure
 317 make
 318 make install
 319
 320
 321
 322
 323 ***********************************************************
 324 ** Section 3 * Using LTTng and LTTV                      **
 325 ***********************************************************
 326
 327 * Use graphical LTTV to control tracing and analyse traces
 328
 329 lttv-gui (or /usr/local/bin/lttv-gui)
 330   - Spot the "Tracing Control" icon : click on it
 331       (it's a traffic light icon)
 332     - enter the root password
 333     - click "start"
 334     - click "stop"
 335     - Yes
 336       * You should now see a trace
 337
 338 * Use text mode LTTng to control tracing
 339
 340 The tracing can be controlled from a terminal by using the lttctl command (as
 341 root).
 342
 343 Start tracing :
 344
 345 lttctl -n trace -d -l /mnt/relayfs/ltt -t /tmp/trace
 346
 347 Stop tracing and destroy trace channels :
 348
 349 lttctl -n trace -R
 350
 351 see lttctl --help for details.
 352
 353
 354 * Use text mode LTTV
 355
 356 Fell free to look in /usr/local/lib/lttv/plugins to see all the text and
 357 graphical plugins available.
 358
 359 For example, a simple trace dump in text format is available with :
 360
 361 lttv -m textDump -t /tmp/trace
 362
 363 see lttv -m textDump --help for detailed command line options of textDump.
 364
 365
 366
 367
 368 ***********************************************************
 369 ** Section 4 * Adding new instrumentations with genevent **
 370 ***********************************************************
 371
 372 * Getting and installing genevent
 373
 374 su -
 375 cd /usr/src
 376 wget http://ltt.polymtl.ca/packages/genevent-0.xx.tar.gz
 377 gzip -cd genevent-0.xx.tar.gz | tar xvof -
 378 cd genevent-0.xx
 379 make
 380 make install
 381
 382
 383 * Add new events to the kernel with genevent
 384
 385 su -
 386 cd /usr/local/share/LinuxTraceToolkitViewer/facilities
 387 cp process.xml yourfacility.xml
 388   * edit yourfacility.xml to fit your needs.
 389 cd /tmp
 390 /usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/facilities/yourfacility.xml
 391 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \
 392          /usr/src/linux-2.6.15-lttng-0.x.xx8/include/linux/ltt
 393 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
 394          /usr/src/linux-2.6.15-lttng-0.x.xx/ltt
 395   * edit the kernel file you want to instrument
 396     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
 397       of the file.
 398     - Add a call to the tracing functions. See their names and parameters in
 399       /usr/src/linux-2.6.15-lttng-0.x.xx/include/linux/ltt/ltt-facility-yourfacility.h
 400
 401
 402