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 and to user space
  11 applications.
  12
  13 What you will typically want is to read sections 2 and 3 : install LTTng from
  14 sources and use it.
  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 ltt-usertrace, 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 30, 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.X-lttng-0.x.xx.tar.bz2
 200 bzip2 -cd patch-2.6.X-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/linux-2.6.X.tar.bz2
 208 bzip2 -cd linux-2.6.X.tar.bz2 | tar xvof -
 209 cd linux-2.6.X
 210 cat /usr/src/lttng/patch-2.6.X-lttng-0.x.xx* | patch -p1
 211 cd ..
 212 mv linux-2.6.X linux-2.6.X-lttng-0.x.xx
 213
 214
 215 * Installing a LTTng kernel
 216
 217 su -
 218 cd /usr/src/linux-2.6.X-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
 247 -- on X86, X86_64
 248 make install
 249 reboot
 250 Select the Linux 2.6.17-lttng-0.x.xx kernel in your boot loader.
 251
 252 -- on PowerPC
 253 cp vmlinux.strip /boot/vmlinux-2.6.X-lttng-0.x.xx
 254 cp System.map /boot/System.map-2.6.X-lttng-0.x.xx
 255 cp .config /boot/config-2.6.X-lttng-0.x.xx
 256 depmod -ae -F /boot/System.map-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx
 257 mkinitrd /boot/initrd.img-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx
 258 (edit /etc/yaboot.conf to add a new entry pointing to your kernel : the entry
 259 that comes first is the default kernel)
 260 ybin
 261 select the right entry at the yaboot prompt (see choices : tab, select : type
 262 the kernel name followed by enter)
 263 Select the Linux 2.6.17-lttng-0.x.xx kernel in your boot loader.
 264 --
 265
 266
 267
 268 * Editing the system wide configuration
 269
 270 You must activate relayfs and specify a mount point. This is typically done in
 271 fstab such that it happens at boot time.
 272
 273 If you have never used RelayFS before, these operation would do this for you :
 274
 275 mkdir /mnt/relayfs
 276 cp /etc/fstab /etc/fstab.lttng.bkp
 277 echo "relayfs         /mnt/relayfs    relayfs rw              0       0"  >> /etc/fstab
 278
 279 then, rebooting or issuing the following command will activate relayfs :
 280
 281 mount /mnt/relayfs
 282
 283 You need to load the ltt-control module to be able to control tracing from user
 284 space. This is done by issuing the command :
 285
 286 modprobe ltt-control
 287
 288 If you want to have complete information about the kernel state (including all
 289 the process names), you need to load the ltt-statedump module. This is done by
 290 issuing the command :
 291
 292 modprobe ltt-statedump
 293
 294 You can automate at boot time loading the ltt-control module by :
 295
 296 echo ltt-control >> /etc/modules
 297 echo ltt-statedump >> /etc/modules
 298
 299
 300 * Getting and installing the ltt-control package (on the traced machine)
 301 (note : the ltt-control package contains lttd and lttctl. Although it has the
 302 same name as the ltt-control kernel module, they are *not* the same thing.)
 303 su -
 304 cd /usr/src
 305 wget http://ltt.polymtl.ca/lttng/ltt-control-0.x-xxxx2006.tar.gz
 306 gzip -cd ltt-control-0.x-xxxx2006.tar.gz | tar xvof -
 307 cd ltt-control-0.x-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 * Getting and installing the ltt-usertrace package for user space tracing
 315 See http://ltt.polymtl.ca/ > USERSPACE TRACING QUICKSTART
 316
 317
 318 * Getting and installing the LTTV package (on the visualisation machine, same or
 319   different from the visualisation machine)
 320
 321 su -
 322 cd /usr/src
 323 wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.x.xx-xxxx2006.tar.gz
 324 gzip -cd LinuxTraceToolkitViewer-0.x.xx-xxxx2006.tar.gz | tar xvof -
 325 cd LinuxTraceToolkitViewer-0.x.xx-xxxx2006
 326 (refer to README to see the development libraries that must be installed on you
 327 system)
 328 ./configure
 329 make
 330 make install
 331
 332
 333
 334
 335 ***********************************************************
 336 ** Section 3 * Using LTTng and LTTV                      **
 337 ***********************************************************
 338
 339 * Use graphical LTTV to control tracing and analyse traces
 340
 341 lttv-gui (or /usr/local/bin/lttv-gui)
 342   - Spot the "Tracing Control" icon : click on it
 343       (it's a traffic light icon)
 344     - enter the root password
 345     - click "start"
 346     - click "stop"
 347     - Yes
 348       * You should now see a trace
 349
 350 * Use text mode LTTng to control tracing
 351
 352 The tracing can be controlled from a terminal by using the lttctl command (as
 353 root).
 354
 355 Start tracing :
 356
 357 lttctl -n trace -d -l /mnt/relayfs/ltt -t /tmp/trace
 358
 359 Stop tracing and destroy trace channels :
 360
 361 lttctl -n trace -R
 362
 363 see lttctl --help for details.
 364
 365
 366 * Use text mode LTTV
 367
 368 Fell free to look in /usr/local/lib/lttv/plugins to see all the text and
 369 graphical plugins available.
 370
 371 For example, a simple trace dump in text format is available with :
 372
 373 lttv -m textDump -t /tmp/trace
 374
 375 see lttv -m textDump --help for detailed command line options of textDump.
 376
 377
 378
 379
 380 ***********************************************************
 381 ** Section 4 * Adding new instrumentations with genevent **
 382 ***********************************************************
 383
 384 * Getting and installing genevent
 385
 386 su -
 387 cd /usr/src
 388 wget http://ltt.polymtl.ca/packages/genevent-0.xx.tar.gz
 389 gzip -cd genevent-0.xx.tar.gz | tar xvof -
 390 cd genevent-0.xx
 391 make
 392 make install
 393
 394
 395 * Add new events to the kernel with genevent
 396
 397 su -
 398 cd /usr/local/share/LinuxTraceToolkitViewer/facilities
 399 cp process.xml yourfacility.xml
 400   * edit yourfacility.xml to fit your needs.
 401 cd /tmp
 402 /usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/facilities/yourfacility.xml
 403 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \
 404          /usr/src/linux-2.6.17-lttng-0.x.xx8/include/linux/ltt
 405 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
 406          /usr/src/linux-2.6.17-lttng-0.x.xx/ltt
 407   * edit the kernel file you want to instrument
 408     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
 409       of the file.
 410     - Add a call to the tracing functions. See their names and parameters in
 411       /usr/src/linux-2.6.17-lttng-0.x.xx/include/linux/ltt/ltt-facility-yourfacility.h
 412
 413 * Add new events to userspace programs with genevent
 414 See http://ltt.polymtl.ca/ > USERSPACE TRACING QUICKSTART
 415
 416
 417
 418