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.2.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.2.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     do NOT activate (not ready yet) :
 120        [ ] Align Linux Trace Toolkit Traces
 121        [ ] Activate Linux Trace Toolkit Heartbeat Timer
 122               IMPORTANT : This is enabled by default : you must disable it!
 123     Select <Exit>
 124   Select <Exit>
 125   Select <Yes>
 126 make
 127 make install
 128 make modules_install
 129
 130 You must activate relayfs and specify a mount point. This is typically done in
 131 fstab such that it happens at boot time.
 132
 133 If you have never used RelayFS before, these operation would do this for you :
 134 mkdir /mnt/relayfs
 135 echo "relayfs         /mnt/relayfs    relayfs rw              0       0" \
 136    >> /etc/fstab
 137
 138 reboot
 139
 140   Select the Linux 2.6.12-rc4-mm2-lttng-0.4 kernel in your boot loader.
 141
 142
 143 * Install the ltt-modules
 144
 145 su -
 146 cd /usr/src/lttng/lttng-modules-0.2
 147 KERNELDIR=/usr/src/linux-2.6.12-rc4-mm2-lttng-0.4 make
 148 KERNELDIR=/usr/src/linux-2.6.12-rc4-mm2-lttng-0.4 make modules_install
 149
 150 You need to load the ltt-control module to be able to control tracing from user
 151 space. This is done by issuing the command :
 152 modprobe ltt-control
 153
 154 You can automate at boot time loading the ltt-control module by :
 155 echo ltt-control >> /etc/modules
 156
 157
 158 * Getting and installing the LTTV package
 159
 160 su -
 161 cd /usr/src
 162 wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.6.4-21092005.tar.gz
 163 gzip -cd LinuxTraceToolkitViewer-0.6.4-21092005.tar.gz | tar xvof -
 164 cd LinuxTraceToolkitViewer-0.6.4-21092005
 165 (refer to README to see the development libraries that must be installed on you
 166 system)
 167 ./configure
 168 make
 169 make install
 170
 171
 172
 173
 174 ***********************************************************
 175 ** Section 3 * Using LTTng and LTTV                      **
 176 ***********************************************************
 177
 178 * Use graphical LTTV to control tracing and analyse traces
 179
 180 lttv-gui (or /usr/local/bin/lttv-gui)
 181   - Spot the "Tracing Control" icon : click on it
 182       (it's a traffic light icon)
 183     - enter the root password
 184     - click "start"
 185     - click "stop"
 186     - Yes
 187       * You should now see a trace
 188
 189 * Use text mode LTTng to control tracing
 190
 191 The tracing can be controlled from a terminal by using the lttctl command (as
 192 root).
 193
 194 Start tracing :
 195
 196 lttctl -n trace -d -l /mnt/relayfs/ltt -t /tmp/trace
 197
 198 Stop tracing and destroy trace channels :
 199
 200 lttctl -n trace -R
 201
 202 see lttctl --help for details.
 203
 204
 205 * Use text mode LTTV
 206
 207 Fell free to look in /usr/local/lib/lttv/plugins to see all the text and
 208 graphical plugins available.
 209
 210 For example, a simple trace dump in text format is available with :
 211
 212 lttv -m textDump -t /tmp/trace
 213
 214 see lttv -m textDump --help for detailed command line options of textDump.
 215
 216
 217
 218
 219 ***********************************************************
 220 ** Section 4 * Adding new instrumentations with genevent **
 221 ***********************************************************
 222
 223 * Getting and installing genevent
 224
 225 su -
 226 cd /usr/src
 227 wget http://ltt.polymtl.ca/packages/genevent-0.1.tar.gz
 228 gzip -cd genevent-0.1.tar.gz | tar xvof -
 229 cd genevent-0.1
 230 make
 231 make install
 232
 233
 234 * Add new events to the kernel with genevent
 235
 236 su -
 237 cd /usr/local/share/LinuxTraceToolkitViewer/facilities
 238 cp process.xml yourfacility.xml
 239   * edit yourfacility.xml to fit your needs.
 240 cd /tmp
 241 /usr/local/bin/genevent /usr/local/share/LinuxTraceToolkitViewer/yourfacility.xml
 242 cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \
 243          /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4/include/linux/ltt
 244 cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \
 245          /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4/ltt
 246   * edit the kernel file you want to instrument
 247     - Add #include <linux/ltt/ltt-facility-yourfacility.h> at the beginning
 248       of the file.
 249     - Add a call to the tracing functions. See their names and parameters in
 250       /usr/src/linux-2.6.12-rc4-mm2-lttng-0.4/include/linux/ltt/ltt-facility-yourfacility.h
 251
 252
 253