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