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