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