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