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