X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=trunk%2Flttv%2FQUICKSTART;h=e03abd28dd98a24d1b0e9a62d86f84d10a7983a5;hb=893b05575730f163d2e0288c39b4ea1abd424e6c;hp=a04c24aaa7b69e194681c3af0f8191f50021b023;hpb=d5662043c1570c860ee97af8d6cdd95af95a8c50;p=lttv.git diff --git a/trunk/lttv/QUICKSTART b/trunk/lttv/QUICKSTART index a04c24aa..e03abd28 100644 --- a/trunk/lttv/QUICKSTART +++ b/trunk/lttv/QUICKSTART @@ -1,507 +1,8 @@ Linux Trace Toolkit Quickstart ------------------------------ -Author : Mathieu Desnoyers, September 2005 -Last update : July 31, 2008 +Document officially replaced by +http://www.lttng.org/svn/trunk/lttv/LTTngManual.html +as of January 31st, 2009. -This document is made of four parts : the first one explains how to install -LTTng and LTTV from Debian and RPM binary packages, the second one explains how -to install LTTng and LTTV from sources and the third one describes the steps -to follow to trace a system and view it. The fourth and last part explains -briefly how to add a new trace point to the kernel and to user space -applications. - -What you will typically want is to read sections 2 and 3 : install LTTng from -sources and use it. - -These operations are made for installing the LTTng 0.12 tracer on a linux 2.6.X -kernel. You will also find instructions for installation of LTTV 0.8.x : the -Linux Trace Toolkit Viewer. - -To see the list of compatibilities between LTTng, ltt-control, LTTV, genevent -and ltt-usertrace, please refer to : -http://ltt.polymtl.ca > LTTng+LTTV versions compatibility - - - -The following lttng patch is necessary to have the tracing hooks in the kernel. -The following ltt-control module controls the tracing. - -Required programs and libraries are assumed to be automatically installed in an -installation with Debian or RPM packages. In the case of an installation from -sources, the dependencies are listed. - - -** Current development status ** - -LTTng : -supported architectures : -Intel Pentium (UP/SMP) with TSC -PowerPC 32 and 64 bits -ARM -x86_64 -C2 Microsystems (variant of MIPS) - -LTTV : -supported architectures : -Intel i386 and better -Intel 64 bits -PowerPC 32 and 64 bits - - -*********************************************************** -** Section 1 * Installation from Debian or RPM packages ** -*********************************************************** - -** NOTE : RPM and Debian packages are only made once a version has been - thoroughly tested. If they do not exist at the moment, please install from - sources (see section 2 below). To see the list of compatibilities between - LTTng, ltt-control, LTTV, genevent and lttng-modules, please refer to - http://ltt.polymtl.ca > LTTng+LTTV versions compatibility - - -* Install from RPM packages on Fedora Core 4 : - -Get LTTV RPM from : - -http://ltt.polymtl.ca/packages/fedora/RPMS - -LTTV RPM are ready. - -LTTng kernel and lttng-modules RPM are available for some architectures (i586, -i686). Feel free to help fix the spec files to have correct lttng-modules RPM -package. - - -* Install from .deb packages on Debian : - -You can use the ltt.polymtl.ca apt source to get LTTV for Debian : - -Add the following two sources to your /etc/apt/sources.list : - -deb http://ltt.polymtl.ca/packages/debian experimental main -deb-src http://ltt.polymtl.ca/packages/debian experimental main - - -* Install from precompiled binary packages (LTTV compiled only for i386, and - LTTng only for i686 smp), perform the following : - -su - -apt-get update -apt-get install lttv lttv-doc -apt-get install kernel-image-2.6.12-rc4-mm2-lttng-0.4.2 -apt-get install lttng-modules-modules-2.6.12-rc4-mm2-lttng-0.4.2 - * note : the packages are signed by myself. I am not considered a trusted - Debian source yet, so warnings are normal. - -Then, follow the section "Editing the system wide configuration" in section 2. - -* Create custom LTTV Debian packages - -Binary packages are only available for i386. If you want to create your own LTTV -packages for other platforms, do : - -su - -cd /usr/src -apt-get source lttv -cd lttv-0.6.9 -dpkg-buildpackage -rfakeroot - -You should then have your LTTV .deb files created for your architecture. - -* Create custom LTTng packages - -For building LTTng Debian packages : - -su - -apt-get install kernel-source-2.6.12-rc4-mm2-lttng-0.4.2 -cd /usr/src -bzip2 -cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2.tar.bz2 | tar xvof - -cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2 -make menuconfig (or xconfig or config) (customize your configuration) -make-kpkg kernel_image - -You will then see your freshly created .deb in /usr/src. Install it with -dpkg -i /usr/src/(image-name).deb - -You will also need to create a package for the lttng-modules : - -su - -cd /usr/src -apt-get source lttng-modules -cd kernel-source-2.6.12-rc4-mm2-lttng-0.4.2 -make-kpkg --added_modules /usr/src/lttng-modules-0.3 modules_image - -You will then see your freshly created .deb in /usr/src. Install it with -dpkg -i /usr/src/lttng-modules-modules-(your version).deb - - -Then, follow the section "Editing the system wide configuration" in section 2. - - -*********************************************************** -** Section 2 * Installation from sources ** -*********************************************************** - -* Prerequisites - -Tools needed to follow the package download steps : - -o wget -o bzip2 -o gzip -o tar - -You have to install the standard development libraries and programs necessary -to compile a kernel : - -(from Documentation/Changes in the Linux kernel tree) -o Gnu C 2.95.3 # gcc --version -o Gnu make 3.79.1 # make --version -o binutils 2.12 # ld -v -o util-linux 2.10o # fdformat --version -o module-init-tools 0.9.10 # depmod -V - -You might also want to have libncurses5 to have the text mode kernel -configuration menu, but there are alternatives. - -Prerequisites for LTTV 0.x.x installation are : - -gcc 3.2 or better -gtk 2.4 or better development libraries - (Debian : libgtk2.0, libgtk2.0-dev) - (Fedora : gtk2, gtk2-devel) - note : For Fedora users : this might require at least core 3 from Fedora, - or you might have to compile your own GTK2 library. -glib 2.4 or better development libraries - (Debian : libglib2.0-0, libglib2.0-dev) - (Fedora : glib2, glib2-devel) -libpopt development libraries - (Debian : libpopt0, libpopt-dev) - (Fedora : popt) -libpango development libraries - (Debian : libpango1.0, libpango1.0-dev) - (Fedora : pango, pango-devel) -libc6 development librairies - (Debian : libc6, libc6-dev) - (Fedora : glibc, glibc) - - -* Getting the LTTng packages - -su - -mkdir /usr/src/lttng -cd /usr/src/lttng -(see http://ltt.polymtl.ca/lttng for package listing) -wget http://ltt.polymtl.ca/lttng/patch-2.6.X-lttng-0.x.xx.tar.bz2 -bzip2 -cd patch-2.6.X-lttng-0.x.xx.tar.bz2 | tar xvof - - - -* Getting LTTng kernel sources - -su - -cd /usr/src -wget http://kernel.org/pub/linux/kernel/v2.6/linux-2.6.X.tar.bz2 -bzip2 -cd linux-2.6.X.tar.bz2 | tar xvof - -cd linux-2.6.X -- For LTTng 0.9.4- cat /usr/src/lttng/patch*-2.6.X-lttng-0.x.xx* | patch -p1 -- For LTTng 0.9.5+ apply the patches in the order specified in the series file, - or use quilt -cd .. -mv linux-2.6.X linux-2.6.X-lttng-0.x.xx - - -* Installing a LTTng kernel - -su - -cd /usr/src/linux-2.6.X-lttng-0.x.xx -make menuconfig (or make xconfig or make config) - Select the < Help > button if you are not familiar with kernel - configuration. - Items preceded by [*] means they has to be built into the kernel. - Items preceded by [M] means they has to be built as modules. - Items preceded by [ ] means they should be removed. - go to the "General setup" section - Select the following options : - [*] Activate tracepoints - [*] Activate markers - [*] Activate userspace markers ABI - <*> Compile generic tracing probes - Linux Trace Toolkit ---> - [LTTng fine-grained-timestamping] - [*] Linux Trace Toolkit Instrumentation Support - or <*> Linux Trace Toolkit Relay+DebugFS Support - or <*> Linux Trace Toolkit Serializer - or <*> Linux Trace Toolkit Marker Control - or <*> Linux Trace Toolkit Tracer - It makes no difference for the rest of the procedure whether the Tracer - is compiled built-in or as a module. - activate : - [*] Align Linux Trace Toolkit Traces - Linux Trace Toolkit Netlink Controller - Linux Trace Toolkit State Dump - your choice (see < Help >) : - [ ] Write heartbeat event to shrink traces - [ ] Support trace extraction from crash dump - Select - Select - Select -make -make modules_install -(if necessary, create a initrd with mkinitrd or your preferate alternative) -(mkinitrd -o /boot/initrd.img-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx) - --- on X86, X86_64 -make install -reboot -Select the Linux 2.6.17-lttng-0.x.xx kernel in your boot loader. - --- on PowerPC -cp vmlinux.strip /boot/vmlinux-2.6.X-lttng-0.x.xx -cp System.map /boot/System.map-2.6.X-lttng-0.x.xx -cp .config /boot/config-2.6.X-lttng-0.x.xx -depmod -ae -F /boot/System.map-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx -mkinitrd /boot/initrd.img-2.6.X-lttng-0.x.xx 2.6.X-lttng-0.x.xx -(edit /etc/yaboot.conf to add a new entry pointing to your kernel : the entry -that comes first is the default kernel) -ybin -select the right entry at the yaboot prompt (see choices : tab, select : type -the kernel name followed by enter) -Select the Linux 2.6.17-lttng-0.x.xx kernel in your boot loader. --- - - - -* Editing the system wide configuration - -You must activate debugfs and specify a mount point. This is typically done in -fstab such that it happens at boot time. - -If you have never used DebugFS before, these operation would do this for you : - -mkdir /mnt/debugfs -cp /etc/fstab /etc/fstab.lttng.bkp -echo "debugfs /mnt/debugfs debugfs rw 0 0" >> /etc/fstab - -then, rebooting or issuing the following command will activate debugfs : - -mount /mnt/debugfs - -You need to load the LTT modules to be able to control tracing from user -space. This is done by issuing the following commands. Note however -these commands load all LTT modules. Depending on what options you chose to -compile statically, you may not need to issue all these commands. - -modprobe ltt-control -modprobe ltt-marker-control -modprobe ltt-tracer -modprobe ltt-serialize -modprobe ltt-relay -modprobe ipc-trace -modprobe kernel-trace -modprobe mm-trace -modprobe net-trace -modprobe fs-trace - -If you want to have complete information about the kernel state (including all -the process names), you need to load the ltt-statedump module. This is done by -issuing the command : - -modprobe ltt-statedump - -You can automate at boot time loading the ltt-control module by : - -cp /etc/modules /etc/modules.bkp -echo ltt-control >> /etc/modules -echo ltt-marker-control >> /etc/modules -echo ltt-tracer >> /etc/modules -echo ltt-serialize >> /etc/modules -echo ltt-relay >> /etc/modules -echo ipc-trace >> /etc/modules -echo kernel-trace >> /etc/modules -echo mm-trace >> /etc/modules -echo net-trace >> /etc/modules -echo fs-trace >> /etc/modules - - -* Getting and installing the ltt-control package (on the traced machine) -(note : the ltt-control package contains lttd and lttctl. Although it has the -same name as the ltt-control kernel module, they are *not* the same thing.) -su - -cd /usr/src -wget http://ltt.polymtl.ca/lttng/ltt-control-0.x-xxxx2006.tar.gz -gzip -cd ltt-control-0.x-xxxx2006.tar.gz | tar xvof - -cd ltt-control-0.x-xxxx2006 -(refer to README to see the development libraries that must be installed on you -system) -./configure -make -make install - -* Getting and installing the markers-userspace package for user space tracing -See http://ltt.polymtl.ca/packages/markers-userspace-0.5.tar.bz2 or more recent. - - -* Getting and installing the LTTV package (on the visualisation machine, same or - different from the visualisation machine) - -su - -cd /usr/src -wget http://ltt.polymtl.ca/packages/LinuxTraceToolkitViewer-0.x.xx-xxxx2006.tar.gz -gzip -cd LinuxTraceToolkitViewer-0.x.xx-xxxx2006.tar.gz | tar xvof - -cd LinuxTraceToolkitViewer-0.x.xx-xxxx2006 -(refer to README to see the development libraries that must be installed on your -system) -./configure -make -make install - - - - -*********************************************************** -** Section 3 * Using LTTng and LTTV ** -*********************************************************** - -* Arm Linux Kernel Markers after each boot - -ltt-armall - -* Use graphical LTTV to control tracing and analyse traces - -lttv-gui (or /usr/local/bin/lttv-gui) - - Spot the "Tracing Control" icon : click on it - (it's a traffic light icon) - - enter the root password - - click "start" - - click "stop" - - Yes - * You should now see a trace - -* Use text mode LTTng to control tracing - -The tracing can be controlled from a terminal by using the lttctl command (as -root). - -Start tracing : - -lttctl -n trace -d -l /mnt/debugfs/ltt -t /tmp/trace - -Stop tracing and destroy trace channels : - -lttctl -n trace -R - -see lttctl --help for details. - -(note : to see if the buffers has been filled, look at the dmesg output after -lttctl -R or after stopping tracing from the GUI, it will show an event lost -count. If it is the case, try using larger buffers. See lttctl --help to learn -how.) - -* Use text mode LTTV - -Feel free to look in /usr/local/lib/lttv/plugins to see all the text and -graphical plugins available. - -For example, a simple trace dump in text format is available with : - -lttv -m textDump -t /tmp/trace - -see lttv -m textDump --help for detailed command line options of textDump. - -It is, in the current state of the project, very useful to use "grep" on the -text output to filter by specific event fields. You can later copy the timestamp -of the events to the clipboard and paste them in the GUI by clicking on the -bottom right label "Current time". Support for this type of filtering should -be added to the filter module soon. - -* Hybrid mode - -Starting from LTTng 0.5.105 and ltt-control 0.20, a new mode can be used : -hybrid. It can be especially useful when studying big workloads on a long period -of time. - -When using this mode, the most important, low rate control information will be -recorded during all the trace by lttd (i.e. process creation/exit). The high -rate information (i.e. interrupt/traps/syscall entry/exit) will be kept in a -flight recorder buffer (now named flight-channelname_X). - -The following lttctl commands take an hybrid trace : - -Create trace channel, start lttd on normal channels, start tracing: -lttctl -n tracename -d -l /mnt/relayfs/ltt -t /tmp/trace1 -m hybrid - -Stop tracing, start lttd on flight recorder channels, destroy trace channels : -lttctl -n tracename -f -l /mnt/relayfs/ltt -t /tmp/trace1 -m hybrid - - -We will need to tweak what we consider "important" medium rate events. For -instance, thread branding events are actually considered a "high rate" event -when it should be considered "medium rate". The same should apply for the -state dump process enumeration. - -* Flight recorder mode - -The flight recorder mode writes data into overwritten buffers for all channels, -including control channels, except for the facilities tracefiles. - -The following lttctl commands take a flight recorder trace : - -lttctl -n trace -c -m flight -lttd -n -d -t /tmp/trace -c /sys/kernel/debug/ltt -lttctl -n trace -s -.. do stuff -lttctl -n trace -q -lttd -f -d -t /tmp/trace -c /sys/kernel/debug/ltt -lttctl -m trace -r - - -*********************************************************** -** Section 4 * Adding new instrumentations with genevent ** -*********************************************************** - -* Getting and installing genevent - -su - -cd /usr/src -wget http://ltt.polymtl.ca/packages/genevent-0.xx.tar.gz -gzip -cd genevent-0.xx.tar.gz | tar xvof - -cd genevent-0.xx -make -make install - - -* Add new events to the kernel with genevent (deprecated in LTTng 0.9.x) - -su - -cd /usr/local/share/ltt-control/facilities -cp process.xml yourfacility.xml - * edit yourfacility.xml to fit your needs. -cd /tmp -/usr/local/bin/genevent /usr/local/share/ltt-control/facilities/yourfacility.xml -cp ltt-facility-yourfacility.h ltt-facility-id-yourfacility.h \ - /usr/src/linux-2.6.17-lttng-0.x.xx8/include/ltt -cp ltt-facility-loader-yourfacility.c ltt-facility-loader-yourfacility.h \ - /usr/src/linux-2.6.17-lttng-0.x.xx/ltt/facilities - * edit the kernel file you want to instrument to add a marker to it. See - include/linux/marker.h. - * create a dynamically loadable probe. See ltt/probes for examples. The probe - will be connected to your marker and will typically call the logging - functions found in the header file you created with genevent. - -* Add new kernel events - -*Important* note : in its current state, LTTng and LTTV needs the programmer -to keep the marker/probe format string and the XML description of the -event data types in sync by hand. Failure to do so will result in errors in -LTTV. - -See the markers documentation to see how to describe the marker. You will need -to clone probe modules found in ltt/probes to connect them to the markers so -that the information can be recorded in the trace. - -* Add new events to userspace programs with genevent -See http://ltt.polymtl.ca/ > USERSPACE TRACING QUICKSTART - -User-space tracing still uses genevent, which is subject to change in a near -future. +Mathieu Desnoyers