<h1>Linux Trace Toolkit Next Generation Manual</h1>
Author : Mathieu Desnoyers, September 2005<br>
-Last update : January 21st, 2009<br>
+Last update : September 3, 2010<br>
(originally known as the LTTng QUICKSTART guide)
<h2>Table of Contents</h2>
<ul>
<li><a href="#intro" name="TOCintro">Introduction</a></li>
<ul>
+<li><a href="#licenses" name="TOClicenses">Licenses</a></li>
+<ul>
<li><a href="#arch" name="TOCarch">Supported architectures</a></li>
</ul>
These operations are made for installing the LTTng 0.86 tracer on a linux 2.6.X
kernel. You will also find instructions for installation of LTTV 0.12.x : the
Linux Trace Toolkit Viewer.
-To see the list of compatibilities between LTTng, ltt-control, LTTV, please
-refer to :
+To see the list of compatibilities between the LTTng kernel patchset, LTTng
+modules, ltt-control, LTTV, please refer to :
<a
-href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/lttng-lttv-compatibility.html">LTTng+LTTV versions compatibility</a>
+href="http://lttng.org/cgi-bin/gitweb.cgi?p=lttv.git;a=blob_plain;f=doc/developer/lttng-lttv-compatibility.html;hb=HEAD">LTTng+LTTV versions compatibility</a>
The ongoing work had the Linux Kernel Markers integrated in the mainline Linux
kernel since Linux 2.6.24 and the Tracepoints since 2.6.28. In its current
<br>
<br>
+<h3><a href="#TOClicenses" name="licenses">Licenses</a></h3>
+<p>
+LTTng, UST and LTTV are developed by an open community. LTTng is released under
+a dual Gnu LGPLv2.1/GPLv2 license, except for very few kernel-specific files
+which are derived work from the Linux kernel.
+<p>
+LTTV is available under the Gnu GPLv2. The low-level LTTV trace reading library
+is released under Gnu LGPLv2.1.
+<p>
+The Eclipse LTTng trace analysis tool is released under the EPL and uses the
+LTTV trace reading library (LGPLv2.1).
+<p>
+The UST (Userspace Tracing) and the Userspace RCU libraries are released under
+the LGPLv2.1 license, which allows linking with non-GPL (BSD, proprietary...)
+applications. The associated headers are released under MIT-style/BSD-style
+licenses.
+<p>
+Please refer to each particular file licensing for details.
+
<h3><a href="#TOCarch" name="arch">Supported architectures</a></h3>
-<br>
LTTng :<br>
<br>
<li> x86 32/64 bits
(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
+glib 2.16 or better development libraries
(Debian : libglib2.0-0, libglib2.0-dev)
(Fedora : glib2, glib2-devel)
libpopt development libraries
<p>
See the list of compatibilities between LTTng, ltt-control and LTTV at :
<a
-href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/lttng-lttv-compatibility.html">LTTng+LTTV
-versions compatibility</a>.
+href="http://lttng.org/cgi-bin/gitweb.cgi?p=lttv.git;a=blob_plain;f=doc/developer/lttng-lttv-compatibility.html;hb=HEAD">LTTng+LTTV versions compatibility</a>.
<h3><a href="#TOCgetlttng" name="getlttng">Getting the LTTng packages</a></h3>
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
+(see http://lttng.org/files/lttng for package listing)
+wget http://lttng.org/files/lttng/patch-2.6.X-lttng-0.x.xx.tar.bz2
+wget http://lttng.org/files/lttng/lttng-modules-0.x.tar.bz2
bzip2 -cd patch-2.6.X-lttng-0.x.xx.tar.bz2 | tar xvof -
+bzip2 -cd lttng-modules-0.x.tar.bz2 | tar xvof -
</PRE>
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
+ 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.
Select the following options :
[*] Prompt for development and/or incomplete code/drivers
[*] Activate markers
- [*] Activate userspace markers ABI (experimental, optional)
[*] Immediate value optimization (optional)
- [*] Linux Trace Toolkit Next Generation (LTTng) --->
- <M> or <*> Compile lttng tracing probes
- <M> or <*> Linux Trace Toolkit High-speed Lockless Data Relay
- <M> or <*> Linux Trace Toolkit Lock-Protected Data Relay
- <M> or <*> Linux Trace Toolkit Serializer
- <M> or <*> Linux Trace Toolkit Marker Control
- <M> or <*> Linux Trace Toolkit Tracer
- [*] Align Linux Trace Toolkit Traces
- <M> or <*> Support logging events from userspace
- [*] Support trace extraction from crash dump
- <M> or <*> Linux Trace Toolkit Trace Controller
- <M> or <*> Linux Trace Toolkit State Dump
- Select <Exit>
- Select <Exit>
- Select <Yes>
+ Select <Exit>
+ Select <Exit>
+ Select <Yes>
make
make modules_install
(if necessary, create a initrd with mkinitrd or your preferate alternative)
--
</PRE>
+
+<h3><a href="#TOCinstalllttng" name="installlttng">Installing the LTTng modules</a></h3>
+
+<PRE>
+su -
+cd /usr/src/lttng/lttng-modules-0.x
+KERNELDIR=/usr/src/linux-2.6.X-lttng-0.x.xx make
+KERNELDIR=/usr/src/linux-2.6.X-lttng-0.x.xx make modules_install
+
+Optionally, make can be prefixed with tracer options:
+
+EXTRA_CFLAGS="-DLTT_DEBUG_EVENT_SIZE" make
+EXTRA_CFLAGS="-DLTT_VMCORE" make
+EXTRA_CFLAGS="-DLTT_DEBUG_EVENT_SIZE -DLTT_VMCORE" make
+</PRE>
+
<h3><a href="#TOCeditconfig" name="editconfig">Editing the system wide
configuration</a></h3>
modprobe ltt-trace-control
modprobe ltt-marker-control
modprobe ltt-tracer
-modprobe ltt-serialize
modprobe ltt-relay
modprobe ipc-trace
modprobe kernel-trace
modprobe ext4-trace
modprobe syscall-trace
modprobe trap-trace
+modprobe block-trace
#if locking tracing is wanted, uncomment the following
#modprobe lockdep-trace
</PRE>
echo ltt-trace-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
<PRE>
su -
cd /usr/src
-wget http://ltt.polymtl.ca/lttng/ltt-control-0.x-xxxx2006.tar.gz
+wget http://lttng.org/files/lttng/ltt-control-0.x-xxxx2006.tar.gz
gzip -cd ltt-control-0.x-xxxx2008.tar.gz | tar xvof -
cd ltt-control-0.x-xxxx2006
(refer to README to see the development libraries that must be installed on you
<PRE>
Make sure you selected the kernel menuconfig option :
- <M> or <*> Support logging events from userspace
+ <M> or <*> Support logging events from userspace
And that the ltt-userspace-event kernel module is loaded if selected as a
module.
Simple userspace tracing is available through
-echo "some text to record" > /mnt/debugfs/ltt/write_event
+echo "some text to record" > /mnt/debugfs/ltt/write_event
It will appear in the trace under event :
channel : userspace
<PRE>
su -
cd /usr/src
-wget http://ltt.polymtl.ca/packages/lttv-0.x.xx-xxxx2008.tar.gz
+wget http://lttng.org/files/packages/lttv-0.x.xx-xxxx2008.tar.gz
gzip -cd lttv-0.x.xx-xxxx2008.tar.gz | tar xvof -
cd lttv-0.x.xx-xxxx2008
(refer to README to see the development libraries that must be installed on your
See <a
href="http://git.kernel.org/?p=linux/kernel/git/compudj/linux-2.6-lttng.git;a=blob;f=Documentation/markers.txt">Documentation/markers.txt</a>
and <a
-href="http://git.kernel.org/?p=linux/kernel/git/compudj/linux-2.6-lttng.git;a=blob;f=Documentation/tracepoints.txt">Documentation/tracepoints.txt</a> in your kernel
+href="http://git.kernel.org/?p=linux/kernel/git/compudj/linux-2.6-lttng.git;a=blob;f=Documentation/trace/tracepoints.txt">Documentation/trace/tracepoints.txt</a> in your kernel
tree.
<p>
Also see <a
<h3><a href="#TOCusertp" name="usertp">Adding userspace instrumentation</a></h3>
Add new events to userspace programs with
-<a href="http://ltt.polymtl.ca/packages/">userspace markers packages</a>.
+<a href="http://lttng.org/files/packages/">userspace markers packages</a>.
Get the latest markers-userspace-*.tar.bz2 and see the Makefile and examples. It
allows inserting markers in executables and libraries, currently only on x86_32
and x86_64.
See <a
-href="http://ltt.polymtl.ca/packages/markers-userspace-0.5.tar.bz2">markers-userspace-0.5.tar.bz2</a> or more recent.
+href="http://lttng.org/files/packages/markers-userspace-0.5.tar.bz2">markers-userspace-0.5.tar.bz2</a> or more recent.
<p>
-Note that a new design document for a 3rd generation of tracepoint/marker-based
-userspace tracing is available at <a
-href="http://ltt.polymtl.ca/svn/trunk/lttv/doc/developer/ust.html">LTTng User-space Tracing
-Design</a>. This new infrastructure is not yet implemented.
+Note that tracepoint/marker-based userspace tracing is available at <a
+href="http://lttng.org/ust/">LTTng User-space Tracer (UST)</a>.
<p>
The easy quick-and-dirty way to perform userspace tracing is currently to write