trunk/lttv/QUICKSTART.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <title>Linux Trace Toolkit Quickstart</title>
   5 </head>
   6   <body>
   7
   8 <h1>Linux Trace Toolkit Quickstart</h1>
   9
  10 Author : Mathieu Desnoyers, September 2005<br>
  11 Last update : January 21st, 2009<br>
  12
  13 <h2>Table of Contents</h2>
  14 <ul>
  15
  16 <li><a href="#intro" name="TOCintro">Introduction</a></li>
  17 <li><a href="#section1" name="TOCsection1">Installing LTTng and LTTV from
  18 sources</a></li>
  19 <li><a href="#section2" name="TOCsection2">Using LTTng and LTTV</a></li>
  20 <li><a href="#section3" name="TOCsection3">Adding kernel and user-space
  21 tracepoints</a></li>
  22 <li><a href="#section4" name="TOCsection4">Creating Debian and RPM packages
  23 from LTTV</a>
  24
  25 </ul>
  26
  27 <hr />
  28
  29 <h2><a href="#TOCintro" name="intro">Introduction</a></h2>
  30 <p>
  31 This document is made of four parts : the first one explains how
  32 to install LTTng and LTTV from sources, the second one describes the steps
  33 to follow to trace a system and view it. The third part explains
  34 briefly how to add a new trace point to the kernel and to user space
  35 applications. The fourth and last part explains how to create Debian or RPM
  36 packages from the LTTng and LTTV sources.
  37
  38 <p>
  39 These operations are made for installing the LTTng 0.86 tracer on a linux 2.6.X
  40 kernel. You will also find instructions for installation of LTTV 0.12.x : the
  41 Linux Trace Toolkit Viewer.
  42 To see the list of compatibilities between LTTng, ltt-control, LTTV, please
  43 refer to :
  44 <a
  45 href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/lttng-lttv-compatibility.html">LTTng+LTTV versions compatibility</a>
  46 The lttng patch is necessary to have the tracing hooks in the kernel.
  47
  48 <br>
  49 <br>
  50 Supported architectures :
  51 <br>
  52 LTTng :<br>
  53 <li> x86 32/64 bits
  54 <li> PowerPC 32 and 64 bits
  55 <li> ARM (with limited timestamping precision, e.g. 1HZ. Need
  56 architecture-specific support for better precision)
  57 <li> MIPS
  58 <br>
  59 <br>
  60 LTTV :<br>
  61 <li> Intel 32/64 bits
  62 <li> PowerPC 32 and 64 bits
  63 <li> Possibly others. Takes care of endianness and type size difference between
  64 the LTTng traces and the LTTV analysis tool.
  65
  66 <hr />
  67
  68
  69 <h2><a href="#TOCsection2" name="section2">Installation from sources</a></h2>
  70 <p>
  71
  72 <li>Prerequisites</li>
  73 <ul>
  74 <p>
  75 Tools needed to follow the package download steps :
  76
  77 <li>wget
  78 <li>bzip2
  79 <li>gzip
  80 <li>tar
  81
  82 <p>
  83 You have to install the standard development libraries and programs necessary
  84 to compile a kernel :
  85
  86 (from Documentation/Changes in the Linux kernel tree)
  87 <li>Gnu C &nbsp;               2.95.3 &nbsp;               # gcc --version
  88 <li>Gnu make &nbsp;            3.79.1 &nbsp;               # make --version
  89 <li>binutils  &nbsp;           2.12   &nbsp;               # ld -v
  90 <li>util-linux &nbsp;          2.10o  &nbsp;               # fdformat --version
  91 <li>module-init-tools &nbsp;   0.9.10 &nbsp;               # depmod -V
  92
  93 <p>
  94 You might also want to have libncurses5 to have the text mode kernel
  95 configuration menu, but there are alternatives.
  96
  97 <p>
  98 Prerequisites for LTTV 0.x.x installation are :
  99
 100 <li>gcc 3.2 or better
 101 <li>gtk 2.4 or better development libraries
 102   (Debian : libgtk2.0, libgtk2.0-dev)
 103   (Fedora : gtk2, gtk2-devel)
 104   note : For Fedora users : this might require at least core 3 from Fedora,
 105   or you might have to compile your own GTK2 library.
 106 <li>glib 2.4 or better development libraries
 107   (Debian : libglib2.0-0, libglib2.0-dev)
 108   (Fedora : glib2, glib2-devel)
 109 <li>libpopt development libraries
 110   (Debian : libpopt0, libpopt-dev)
 111   (Fedora : popt)
 112 <li>libpango development libraries
 113   (Debian : libpango1.0, libpango1.0-dev)
 114   (Fedora : pango, pango-devel)
 115 <li>libc6 development librairies
 116   (Debian : libc6, libc6-dev)
 117   (Fedora : glibc, glibc)
 118 </ul>
 119
 120 <li>Reminder/<li>
 121
 122 See the list of compatibilities between LTTng, ltt-control and LTTV at :
 123 <a
 124 href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/lttng-lttv-compatibility.html">LTTng+LTTV
 125 versions compatibility</a>.
 126
 127
 128 * Getting the LTTng packages
 129
 130 su -
 131 mkdir /usr/src/lttng
 132 cd /usr/src/lttng
 133 (see http://ltt.polymtl.ca/lttng for package listing)
 134 wget http://ltt.polymtl.ca/lttng/patch-2.6.X-lttng-0.x.xx.tar.bz2
 135 bzip2 -cd patch-2.6.X-lttng-0.x.xx.tar.bz2 | tar xvof -
 136
 137
 138 * Getting LTTng kernel sources
 139
 140 su -
 141 cd /usr/src
 142 wget http://kernel.org/pub/linux/kernel/v2.6/linux-2.6.X.tar.bz2
 143 bzip2 -cd linux-2.6.X.tar.bz2 | tar xvof -
 144 cd linux-2.6.X
 145 - For LTTng 0.9.4- cat /usr/src/lttng/patch*-2.6.X-lttng-0.x.xx* | patch -p1
 146 - For LTTng 0.9.5+ apply the patches in the order specified in the series file,
 147   or use quilt
 148 cd ..
 149 mv linux-2.6.X linux-2.6.X-lttng-0.x.xx
 150
 151
 152 * Installing a LTTng kernel
 153
 154 su -
 155 cd /usr/src/linux-2.6.X-lttng-0.x.xx
 156 make menuconfig (or make xconfig or make config)
 157     Select the < Help > button if you are not familiar with kernel
 158     configuration.
 159     Items preceded by [*] means they has to be built into the kernel.
 160     Items preceded by [M] means they has to be built as modules.
 161     Items preceded by [ ] means they should be removed.
 162   go to the "General setup" section
 163     Select the following options :
 164     [*] Prompt for development and/or incomplete code/drivers
 165     [*] Activate markers
 166     [*] Activate userspace markers ABI (experimental, optional)
 167     [*] Immediate value optimization (optional)
 168     [*] Linux Trace Toolkit Next Generation (LTTng) --->
 169     <M> or <*> Compile lttng tracing probes
 170     <M> or <*> Linux Trace Toolkit High-speed Lockless Data Relay
 171     <M> or <*> Linux Trace Toolkit Lock-Protected Data Relay
 172     <M> or <*> Linux Trace Toolkit Serializer
 173     <M> or <*>   Linux Trace Toolkit Marker Control
 174     <M> or <*>     Linux Trace Toolkit Tracer
 175     [*] Align Linux Trace Toolkit Traces
 176     <M> or <*> Support logging events from userspace
 177     [*] Support trace extraction from crash dump
 178     <M> or <*> Linux Trace Toolkit Trace Controller
 179     <M> or <*> Linux Trace Toolkit State Dump
 180   Select <Exit>
 181   Select <Exit>
 182   Select <Yes>
 183 make
 184 make modules_install
 185 (if necessary, create a initrd with mkinitrd or your preferate alternative)
 186 (mkinitrd -o /boot/initrd.img-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx)
 187
 188 -- on X86, X86_64
 189 make install
 190 reboot
 191 Select the Linux 2.6.X-lttng-0.x.xx kernel in your boot loader.
 192
 193 -- on PowerPC
 194 cp vmlinux.strip /boot/vmlinux-2.6.X-lttng-0.x.xx
 195 cp System.map /boot/System.map-2.6.X-lttng-0.x.xx
 196 cp .config /boot/config-2.6.X-lttng-0.x.xx
 197 depmod -ae -F /boot/System.map-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx
 198 mkinitrd /boot/initrd.img-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx
 199 (edit /etc/yaboot.conf to add a new entry pointing to your kernel : the entry
 200 that comes first is the default kernel)
 201 ybin
 202 select the right entry at the yaboot prompt (see choices : tab, select : type
 203 the kernel name followed by enter)
 204 Select the Linux 2.6.X-lttng-0.x.xx kernel in your boot loader.
 205 --
 206
 207
 208
 209 * Editing the system wide configuration
 210
 211 You must activate debugfs and specify a mount point. This is typically done in
 212 fstab such that it happens at boot time.
 213
 214 If you have never used DebugFS before, these operation would do this for you :
 215
 216 mkdir /mnt/debugfs
 217 cp /etc/fstab /etc/fstab.lttng.bkp
 218 echo "debugfs         /mnt/debugfs    debugfs rw              0       0"  >> /etc/fstab
 219
 220 then, rebooting or issuing the following command will activate debugfs :
 221
 222 mount /mnt/debugfs
 223
 224 You need to load the LTT modules to be able to control tracing from user
 225 space. This is done by issuing the following commands. Note however
 226 these commands load all LTT modules. Depending on what options you chose to
 227 compile statically, you may not need to issue all these commands.
 228
 229 modprobe ltt-trace-control
 230 modprobe ltt-marker-control
 231 modprobe ltt-tracer
 232 modprobe ltt-serialize
 233 modprobe ltt-relay
 234 modprobe ipc-trace
 235 modprobe kernel-trace
 236 modprobe mm-trace
 237 modprobe net-trace
 238 modprobe fs-trace
 239 modprobe jbd2-trace
 240 modprobe ext4-trace
 241 modprobe syscall-trace
 242 modprobe trap-trace
 243 #if locking tracing is wanted, uncomment the following
 244 #modprobe lockdep-trace
 245
 246 If you want to have complete information about the kernel state (including all
 247 the process names), you need to load the ltt-statedump module. This is done by
 248 issuing the command :
 249
 250 modprobe ltt-statedump
 251
 252 You can automate at boot time loading the ltt-control module by :
 253
 254 cp /etc/modules /etc/modules.bkp
 255 echo ltt-trace-control >> /etc/modules
 256 echo ltt-marker-control >> /etc/modules
 257 echo ltt-tracer >> /etc/modules
 258 echo ltt-serialize >> /etc/modules
 259 echo ltt-relay >> /etc/modules
 260 echo ipc-trace >> /etc/modules
 261 echo kernel-trace >> /etc/modules
 262 echo mm-trace >> /etc/modules
 263 echo net-trace >> /etc/modules
 264 echo fs-trace >> /etc/modules
 265 echo jbd2-trace >> /etc/modules
 266 echo ext4-trace >> /etc/modules
 267 echo syscall-trace >> /etc/modules
 268 echo trap-trace >> /etc/modules
 269 #if locking tracing is wanted, uncomment the following
 270 #echo lockdep-trace >> /etc/modules
 271
 272
 273 * Getting and installing the ltt-control package (on the traced machine)
 274 (note : the ltt-control package contains lttd and lttctl. Although it has the
 275 same name as the ltt-control kernel module, they are *not* the same thing.)
 276 su -
 277 cd /usr/src
 278 wget http://ltt.polymtl.ca/lttng/ltt-control-0.x-xxxx2006.tar.gz
 279 gzip -cd ltt-control-0.x-xxxx2008.tar.gz | tar xvof -
 280 cd ltt-control-0.x-xxxx2006
 281 (refer to README to see the development libraries that must be installed on you
 282 system)
 283 ./configure
 284 make
 285 make install
 286
 287
 288 * Userspace tracing
 289
 290 Make sure you selected the kernel menuconfig option :
 291     <M> or <*> Support logging events from userspace
 292 And that the ltt-userspace-event kernel module is loaded if selected as a
 293 module.
 294
 295 Simple userspace tracing is available through
 296 echo "some text to record" > /mnt/debugfs/ltt/write_event
 297
 298 It will appear in the trace under event :
 299 channel : userspace
 300 event name : event
 301
 302
 303 * Getting and installing the LTTV package (on the visualisation machine, same or
 304   different from the visualisation machine)
 305
 306 su -
 307 cd /usr/src
 308 wget http://ltt.polymtl.ca/packages/lttv-0.x.xx-xxxx2008.tar.gz
 309 gzip -cd lttv-0.x.xx-xxxx2008.tar.gz | tar xvof -
 310 cd lttv-0.x.xx-xxxx2008
 311 (refer to README to see the development libraries that must be installed on your
 312 system)
 313 ./configure
 314 make
 315 make install
 316
 317
 318 * Getting and installing the markers-userspace package for user space tracing
 319 (experimental)
 320 See http://ltt.polymtl.ca/packages/markers-userspace-0.5.tar.bz2 or more recent.
 321
 322
 323
 324 ***********************************************************
 325 ** Section 3 * Using LTTng and LTTV                      **
 326 ***********************************************************
 327
 328 * IMPORTANT : Arm Linux Kernel Markers after each boot
 329
 330 ltt-armall
 331
 332 * Use graphical LTTV to control tracing and analyse traces
 333
 334 lttv-gui (or /usr/local/bin/lttv-gui)
 335   - Spot the "Tracing Control" icon : click on it
 336       (it's a traffic light icon)
 337     - enter the root password
 338     - click "start"
 339     - click "stop"
 340     - Yes
 341       * You should now see a trace
 342
 343 * Use text mode LTTng to control tracing
 344
 345 The tracing can be controlled from a terminal by using the lttctl command (as
 346 root).
 347
 348 Start tracing :
 349
 350 lttctl -C -w /tmp/trace1 trace1
 351
 352 Stop tracing and destroy trace channels :
 353
 354 lttctl -D trace1
 355
 356 see lttctl --help for details.
 357
 358 (note : to see if the buffers has been filled, look at the dmesg output after
 359 lttctl -R or after stopping tracing from the GUI, it will show an event lost
 360 count. If it is the case, try using larger buffers. See lttctl --help to learn
 361 how. lttv now also shows event lost messages in the console when loading a trace
 362 with missing events or lost subbuffers.)
 363
 364 * Use text mode LTTV
 365
 366 Feel free to look in /usr/local/lib/lttv/plugins to see all the text and
 367 graphical plugins available.
 368
 369 For example, a simple trace dump in text format is available with :
 370
 371 lttv -m textDump -t /tmp/trace
 372
 373 see lttv -m textDump --help for detailed command line options of textDump.
 374
 375 It is, in the current state of the project, very useful to use "grep" on the
 376 text output to filter by specific event fields. You can later copy the timestamp
 377 of the events to the clipboard and paste them in the GUI by clicking on the
 378 bottom right label "Current time". Support for this type of filtering should
 379 be added to the filter module soon.
 380
 381 * Hybrid mode
 382
 383 Starting from LTTng 0.5.105 and ltt-control 0.20, a new mode can be used :
 384 hybrid. It can be especially useful when studying big workloads on a long period
 385 of time.
 386
 387 When using this mode, the most important, low rate control information will be
 388 recorded during all the trace by lttd (i.e. process creation/exit). The high
 389 rate information (i.e. interrupt/traps/syscall entry/exit) will be kept in a
 390 flight recorder buffer (now named flight-channelname_X).
 391
 392 The following lttctl commands take an hybrid trace :
 393
 394 Create trace channel, start lttd on normal channels, start tracing:
 395 lttctl -C -w /tmp/trace2 -o channel.kernel.overwrite=1 trace2
 396
 397 Stop tracing, start lttd on flight recorder channels, destroy trace channels :
 398 lttctl -D -w /tmp/trace2 trace2
 399
 400 Each "overwrite" channel is flight recorder channel.
 401
 402 * Flight recorder mode
 403
 404 The flight recorder mode writes data into overwritten buffers for all channels,
 405 including control channels, except for the facilities tracefiles. It consists of
 406 setting all channels to "overwrite".
 407
 408 The following lttctl commands take a flight recorder trace :
 409
 410 lttctl -C -w /tmp/trace3 -o channel.all.overwrite=1 trace3
 411 ...
 412 lttctl -D -w /tmp/trace3 trace3
 413
 414
 415 **************************************************************
 416 ** Section 4 * Adding new instrumentations with the markers **
 417 **************************************************************
 418
 419 See Documentation/markers.txt and Documentation/tracepoints.txt in your kernel
 420 tree.
 421
 422 * Add new events to userspace programs with userspace markers
 423 http://ltt.polymtl.ca/packages/
 424
 425 Get the latest markers-userspace-*.tar.bz2 and see the Makefile and examples. It
 426 allows inserting markers in executables and libraries, currently only on x86_32
 427 and x86_64.
 428
 429 ***********************************************************
 430 ** Section 5 * Creating Debian or RPM packages           **
 431 ***********************************************************
 432
 433 * Create custom LTTV Debian packages
 434
 435 Use : dpkg-buildpackage -rfakeroot
 436
 437 You should then have your LTTV .deb files created for your architecture.
 438
 439 * Create custom LTTng packages
 440
 441 For building LTTng Debian packages :
 442
 443 Get the build tree with patches applies as explained in section 2.
 444
 445 make menuconfig (or xconfig or config) (customize your configuration)
 446 make-kpkg kernel_image
 447
 448 You will then see your freshly created .deb in /usr/src. Install it with
 449 dpkg -i /usr/src/(image-name).deb
 450
 451 Then, follow the section "Editing the system wide configuration" in section 2.
 452
 453
 454
 455   </body>
 456 </html>