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.4.1 tracer on a
  17 linux 2.6.12-rc4-mm2 kernel. You will also find instructions for installtion of
  18 LTTV 0.6.x : the Linux Trace Toolkit Viewer.
  19
  20 At this point, the -mm tree of the kernel is used because it has RelayFS support
  21 in it. In a nearby future, a vanilla kernel 2.6.14 will be used, as RelayFS has
  22 been integrated in the linux 2.6.14-rc series.
  23
  24 The following lttng patch is necessary to have the tracing hooks in the kernel.
  25 The following ltt-control module controls the tracing.
  26
  27 Required programs and librairies are assumed to be automatically installed in an
  28 installation with Debian or RPM packages. In the case of an installation from
  29 sources, the dependencies are listed.
  30
  31
  32 ** Current development status **
  33
  34 LTTng :
  35 supported architectures :
  36 Intel Pentium (UP/SMP) with TSC
  37
  38 LTTV :
  39 supported architectures :
  40 Intel i386 and better
  41 PowerPC
  42
  43
  44
  45 Author : Mathieu Desnoyers, September 2005
  46
  47
  48
  49 ***********************************************************
  50 ** Section 1 * Installation from Debian or RPM packages  **
  51 ***********************************************************
  52
  53 No RPM packages are ready yet.
  54
  55 You can use the ltt.polymtl.ca apt source to get LTTV for Debian :
  56
  57 Add the following two sources to your /etc/apt/sources.list :
  58
  59 deb http://ltt.polymtl.ca/packages/debian experimental main
  60 deb-src http://ltt.polymtl.ca/packages/debian experimental main
  61
  62
  63 * Install from precompiled binary packages (LTTV compiled only for i386, and
  64   LTTng only for i686 smp), perform the following :
  65
  66 su -
  67 apt-get update
  68 apt-get install lttv lttv-doc
  69 apt-get install kernel-image-2.6.12-rc4-mm2-lttng-0.4.1
  70 apt-get install lttng-modules-modules-2.6.12-rc4-mm2-lttng-0.4.1
  71   * note : the packages are signed by myself. I am not considered a trusted
  72     Debian source yet, so warnings are normal.
  73
  74 Then, follow the section "Editing the system wide configuration" in section 2.
  75
  76 * Create custom LTTV Debian packages
  77
  78 Binary packages are only available for i386. If you want to create your own LTTV
  79 packages for other platforms, do :
  80
  81 su -
  82 cd /usr/src
  83 apt-get source lttv
  84 cd lttv-0.6.8
  85 dpkg-buildpackage -rfakeroot
  86
  87 You should then have your LTTV .deb files created for your architecture.
  88
  89 * Create custom LTTng packages
  90
  91 For building LTTng Debian packages :
  92
  93 su -
  94 apt-get install kernel-source-2.6.12-rc4-mm2-lttng-0.4.1
  95 cd /usr/src
  96 bzip2 -cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.1.tar.bz2 | tar xvof -
  97 cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.1
  98 make menuconfig (or xconfig or config) (customize your configuration)
  99 make-kpkg kernel_image
 100
 101 You will then see your freshly created .deb in /usr/src. Install it with
 102 dpkg -i /usr/src/(image-name).deb
 103
 104 You will also need to create a package for the lttng-modules :
 105
 106 su -
 107 cd /usr/src
 108 apt-get source lttng-modules
 109 cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.1
 110 make-kpkg --added_modules /usr/src/lttng-modules-0.3 modules_image
 111
 112 You will then see your freshly created .deb in /usr/src. Install it with
 113 dpkg -i /usr/src/lttng-modules-modules-(your version).deb
 114
 115
 116 Then, follow the section "Editing the system wide configuration" in section 2.
 117
 118
 119 ***********************************************************
 120 ** Section 2 * Installation from sources                 **
 121 ***********************************************************
 122
 123 * Prerequisites
 124
 125 Tools needed to follow the package download steps :
 126
 127 o wget
 128 o bzip2
 129 o gzip
 130 o tar
 131
 132 You have to install the standard development librairies and programs necessary
 133 to compile a kernel :
 134
 135 (from Documentation/Changes in the Linux kernel tree)
 136 o  Gnu C                  2.95.3                  # gcc --version
 137 o  Gnu make               3.79.1                  # make --version
 138 o  binutils               2.12                    # ld -v
 139 o  util-linux             2.10o                   # fdformat --version
 140 o  module-init-tools      0.9.10                  # depmod -V
 141
 142 You might also want to have libncurses5 to have the text mode kernel
 143 configuration menu, but there are alternatives.
 144
 145 Prerequisites for LTTV 0.6.x installation are :
 146
 147 gtk 2.4 or better development libraries (libgtk2.0, libgtk2.0-dev)
 148 glib 2.4 or better development libraries (libglib2.0-0, libglib2.0-dev)
 149 libpopt development libraries (libpopt0, libpopt-dev)
 150 libpango development libraries (libpango1.0, libpango1.0-dev)
 151 libc6 development librairies (libc6, libc6-dev)
 152
 153
 154 * Getting the LTTng packages
 155
 156 su -
 157 mkdir /usr/src/lttng
 158 cd /usr/src/lttng
 159 (see http://ltt.polymtl.ca/lttng for package listing)
 160 wget http://ltt.polymtl.ca/lttng/lttng-modules-0.3.tar.bz2
 161 wget http://ltt.polymtl.ca/lttng/patch-2.6.12-rc4-mm2-lttng-0.4.1.bz2
 162 bzip2 -cd lttng-modules-0.3.tar.bz2 | tar xvof -
 163
 164
 165 * Getting LTTng kernel sources
 166
 167 su -
 168 cd /usr/src
 169 wget http://kernel.org/pub/linux/kernel/v2.6/testing/linux-2.6.12-rc4.tar.bz2
 170 wget http://kernel.org/pub/linux/kernel/people/akpm/patches/2.6/2.6.12-rc4/2.6.12-rc4-mm2/2.6.12-rc4-mm2.bz2
 171 bzip2 -cd linux-2.6.12-rc4.tar.bz2 | tar xvof -
 172 cd linux-2.6.12-rc4
 173 bzip2 -cd ../2.6.12-rc4-mm2.bz2 | patch -p1
 174 bzip2 -cd /usr/src/lttng/patch-2.6.12-rc4-mm2-lttng-0.4.1.bz2 | patch -p1
 175 cd ..
 176 mv linux-2.6.12-rc4 linux-2.6.12-rc4-mm2-lttng-0.4.1
 177
 178
 179 * Installing a LTTng kernel
 180
 181 su -
 182 cd /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4.1
 183 make menuconfig (or make xconfig or make config)
 184     Select the < Help > button if you are not familiar with kernel
 185     configuration.
 186     Items preceded by [*] means they has to be built into the kernel.
 187     Items preceded by [M] means they has to be built as modules.
 188     Items preceded by [ ] means they should be removed.
 189   go to the "General setup" section
 190     Select the following options :
 191     [*] Linux Trace Toolkit Instrumentation Support
 192     [M] or [*] Linux Trace Toolkit Tracer
 193         It makes no difference for the rest of the procedure whether the Tracer
 194         is compiled built-in or as a module.
 195     do NOT activate (not ready yet) :
 196        [ ] Align Linux Trace Toolkit Traces
 197        [ ] Activate Linux Trace Toolkit Heartbeat Timer
 198               IMPORTANT : This is enabled by default : you must disable it!
 199     Select <Exit>
 200   Select <Exit>
 201   Select <Yes>
 202 make
 203 make modules_install
 204 make install
 205
 206 reboot
 207
 208   Select the Linux 2.6.12-rc4-mm2-lttng-0.4.1 kernel in your boot loader.
 209
 210
 211 * Install the ltt-modules
 212
 213 su -
 214 cd /usr/src/lttng/lttng-modules-0.3
 215 KERNELDIR=/usr/src/linux-2.6.12-rc4-mm2-lttng-0.4.1 make
 216 KERNELDIR=/usr/src/linux-2.6.12-rc4-mm2-lttng-0.4.1 make modules_install
 217
 218
 219 * Editing the system wide configuration
 220
 221 You must activate relayfs and specify a mount point. This is typically done in
 222 fstab such that it happens at boot time.
 223
 224 If you have never used RelayFS before, these operation would do this for you :
 225
 226 mkdir /mnt/relayfs
 227 cp /etc/fstab /etc/fstab.lttng.bkp
 228 echo "relayfs         /mnt/relayfs    relayfs rw              0       0"  >> /etc/fstab
 229
 230 then, rebooting or issuing the following command will activate relayfs :
 231
 232 mount /mnt/relayfs
 233
 234 You need to load the ltt-control module to be able to control tracing from user
 235 space. This is done by issuing the command :
 236
 237 modprobe ltt-control
 238
 239 You can automate at boot time loading the ltt-control module by :
 240
 241 echo ltt-control >> /etc/modules
 242
 243
 244 * Getting and installing the LTTV package
 245
 246 su -
 247 cd /usr/src
 248 wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.6.8-26092005.tar.gz
 249 gzip -cd LinuxTraceToolkitViewer-0.6.8-26092005.tar.gz | tar xvof -
 250 cd LinuxTraceToolkitViewer-0.6.8-26092005
 251 (refer to README to see the development libraries that must be installed on you
 252 system)
 253 ./configure
 254 make
 255 make install
 256
 257
 258
 259
 260 ***********************************************************
 261 ** Section 3 * Using LTTng and LTTV                      **
 262 ***********************************************************
 263
 264 * Use graphical LTTV to control tracing and analyse traces
 265
 266 lttv-gui (or /usr/local/bin/lttv-gui)
 267   - Spot the "Tracing Control" icon : click on it
 268       (it's a traffic light icon)
 269     - enter the root password
 270     - click "start"
 271     - click "stop"
 272     - Yes
 273       * You should now see a trace
 274
 275 * Use text mode LTTng to control tracing
 276
 277 The tracing can be controlled from a terminal by using the lttctl command (as
 278 root).
 279
 280 Start tracing :
 281
 282 lttctl -n trace -d -l /mnt/relayfs/ltt -t /tmp/trace
 283
 284 Stop tracing and destroy trace channels :
 285
 286 lttctl -n trace -R
 287
 288 see lttctl --help for details.
 289
 290
 291 * Use text mode LTTV
 292
 293 Fell free to look in /usr/local/lib/lttv/plugins to see all the text and
 294 graphical plugins available.
 295
 296 For example, a simple trace dump in text format is available with :
 297
 298 lttv -m textDump -t /tmp/trace
 299
 300 see lttv -m textDump --help for detailed command line options of textDump.
 301
 302
 303
 304
 305 ***********************************************************
 306 ** Section 4 * Adding new instrumentations with genevent **
 307 ***********************************************************
 308
 309 * Getting and installing genevent
 310
 311 su -
 312 cd /usr/src
 313 wget http://ltt.polymtl.ca/packages/genevent-0.2.tar.gz
 314 gzip -cd genevent-0.2.tar.gz | tar xvof -
 315 cd genevent-0.2
 316 make
 317 make install
 318
 319
 320 * Add new events to the kernel with genevent
 321
 322 su -
 323 cd /usr/local/share/LinuxTraceToolkitViewer/facilities
 324 cp process.xml yourfacility.xml
 325   * edit yourfacility.xml to fit your needs.
 326 cd /tmp
 327 /usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/yourfacility.xml
 328 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \
 329          /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4.1/include/linux/ltt
 330 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
 331          /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4.1/ltt
 332   * edit the kernel file you want to instrument
 333     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
 334       of the file.
 335     - Add a call to the tracing functions. See their names and parameters in
 336       /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4.1/include/linux/ltt/ltt-facility-yourfacility.h
 337
 338
 339