The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.8, 20 February 2017
+v2.8, 24 July 2017
include::../common/copyright.txt[]
+include::../common/warning-not-maintained.txt[]
+
+
include::../common/welcome.txt[]
--
[role="term"]
----
-lttng add-context --jul --type='$app.retriever:cur_msg_id'
+$ lttng add-context --jul --type='$app.retriever:cur_msg_id'
----
--
+
--
[role="term"]
----
-lttng enable-event --log4j my_logger \
+$ lttng enable-event --log4j my_logger \
--filter='$app.retriever:cur_msg_id == 23'
----
--
--
[role="term"]
----
-man lttng-enable-event
+$ man lttng-enable-event
----
--
+
[[installing-lttng]]
== Installation
+include::../common/warning-installation-outdated.txt[]
+
**LTTng** is a set of software <<plumbing,components>> which interact to
<<instrumenting,instrument>> the Linux kernel and user applications, and
to <<controlling-tracing,control tracing>> (start and stop
applications.
[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 2 December 2016.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 14 March 2017.
|====
|Distribution |Available in releases |Alternatives
and Ubuntu{nbsp}16.04 _Xenial Xerus_:
link:/docs/v2.9#doc-ubuntu-ppa[use the LTTng Stable{nbsp}2.9 PPA].
+LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_ (not released
+yet).
+
<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other Ubuntu releases.
other Fedora releases.
|https://www.debian.org/[Debian]
-|<<debian,Debian "stretch" (testing)>>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-previous Debian releases.
+|_Not available_
+|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch" (testing)
+and Debian "sid" (unstable)].
+
+<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|https://www.opensuse.org/[openSUSE]
|_Not available_
|_Not available_
|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 from the AUR].
+<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+
|https://alpinelinux.org/[Alpine Linux]
-|<<alpine-linux,Alpine Linux "edge">>.
-|LTTng{nbsp}{revision} for Alpine Linux{nbsp}3.5 (not released yet).
+|_Not available_
+|link:/docs/v2.9#doc-alpine-linux[LTTng{nbsp}2.9 for Alpine Linux "edge"].
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Alpine Linux releases.
+<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES]
|See http://packages.efficios.com/[EfficiOS Enterprise Packages].
|https://buildroot.org/[Buildroot]
|<<buildroot,Buildroot 2016.11>>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+|link:/docs/v2.9#doc-buildroot[LTTng{nbsp}2.9 for Buildroot 2017.02].
+
+<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other Buildroot releases.
|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and
https://www.yoctoproject.org/[Yocto]
|<<oe-yocto,Yocto Project{nbsp}2.2 _Morty_>> (`openembedded-core` layer).
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+|LTTng{nbsp}2.9 for Yocto Project{nbsp}2.3 _Pyro_
+(`openembedded-core` layer) (not released yet).
+
+<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other OpenEmbedded releases.
|====
--
[role="term"]
----
-sudo apt-get install lttng-tools
-sudo apt-get install lttng-modules-dkms
-sudo apt-get install liblttng-ust-dev
+# apt-get install lttng-tools
+# apt-get install lttng-modules-dkms
+# apt-get install liblttng-ust-dev
----
--
--
[role="term"]
----
-sudo apt-get install liblttng-ust-agent-java
+# apt-get install liblttng-ust-agent-java
----
--
--
[role="term"]
----
-sudo apt-get install python3-lttngust
+# apt-get install python3-lttngust
----
--
--
[role="term"]
----
-sudo apt-add-repository ppa:lttng/stable-2.8
-sudo apt-get update
+# apt-add-repository ppa:lttng/stable-2.8
+# apt-get update
----
--
--
[role="term"]
----
-sudo apt-get install lttng-tools
-sudo apt-get install lttng-modules-dkms
-sudo apt-get install liblttng-ust-dev
+# apt-get install lttng-tools
+# apt-get install lttng-modules-dkms
+# apt-get install liblttng-ust-dev
----
--
--
[role="term"]
----
-sudo apt-get install liblttng-ust-agent-java
+# apt-get install liblttng-ust-agent-java
----
--
--
[role="term"]
----
-sudo apt-get install python3-lttngust
+# apt-get install python3-lttngust
----
--
--
[role="term"]
----
-sudo yum install lttng-tools
-sudo yum install lttng-ust
+# yum install lttng-tools
+# yum install lttng-ust
----
--
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.8.tar.bz2 &&
tar -xf lttng-modules-latest-2.8.tar.bz2 &&
cd lttng-modules-2.8.* &&
.Java and Python application instrumentation and tracing
====
If you need to instrument and trace <<java-application,Java
-applications>> on openSUSE, you need to build and install
+applications>> on Fedora, you need to build and install
LTTng-UST{nbsp}{revision} <<building-from-source,from source>> and pass
the `--enable-java-agent-jul`, `--enable-java-agent-log4j`, or
`--enable-java-agent-all` options to the `configure` script, depending
on which Java logging framework you use.
If you need to instrument and trace <<python-application,Python
-applications>> on openSUSE, you need to build and install
+applications>> on Fedora, you need to build and install
LTTng-UST{nbsp}{revision} from source and pass the
`--enable-python-agent` option to the `configure` script.
====
-[[debian]]
-=== Debian
-
-To install LTTng{nbsp}{revision} on Debian "stretch" (testing):
-
-. Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-sudo apt-get install lttng-modules-dkms
-sudo apt-get install liblttng-ust-dev
-sudo apt-get install lttng-tools
-----
---
-
-. **If you need to instrument and trace <<java-application,Java
- applications>>**, install the LTTng-UST Java agent:
-+
---
-[role="term"]
-----
-sudo apt-get install liblttng-ust-agent-java
-----
---
-
-. **If you need to instrument and trace <<python-application,Python
- applications>>**, install the LTTng-UST Python agent:
-+
---
-[role="term"]
-----
-sudo apt-get install python3-lttngust
-----
---
-
-
-[[alpine-linux]]
-=== Alpine Linux
-
-To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
-Alpine Linux "edge":
-
-. Make sure your system is
- https://wiki.alpinelinux.org/wiki/Edge[configured for "edge"].
-. Enable the _testing_ repository by uncommenting the corresponding
- line in path:{/etc/apk/repositories}.
-. Add the LTTng packages:
-+
---
-[role="term"]
-----
-sudo apk add lttng-tools
-sudo apk add lttng-ust-dev
-----
---
-
-To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support)
-on Alpine Linux "edge":
-
-. Add the vanilla Linux kernel:
-+
---
-[role="term"]
-----
-apk add linux-vanilla linux-vanilla-dev
-----
---
-
-. Reboot with the vanilla Linux kernel.
-. Download, build, and install the latest LTTng-modules{nbsp}{revision}:
-+
---
-[role="term"]
-----
-cd $(mktemp -d) &&
-wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.8.tar.bz2 &&
-tar -xf lttng-modules-latest-2.8.tar.bz2 &&
-cd lttng-modules-2.8.* &&
-make &&
-sudo make modules_install &&
-sudo depmod -a
-----
---
-
-
[[enterprise-distributions]]
=== RHEL, SUSE, and other enterprise distributions
--
[role="term"]
----
-make menuconfig
+$ make menuconfig
----
--
.Java and Python application instrumentation and tracing
====
If you need to instrument and trace <<java-application,Java
-applications>> on openSUSE, you need to build and install
+applications>> on Yocto/OpenEmbedded, you need to build and install
LTTng-UST{nbsp}{revision} <<building-from-source,from source>> and pass
the `--enable-java-agent-jul`, `--enable-java-agent-log4j`, or
`--enable-java-agent-all` options to the `configure` script, depending
on which Java logging framework you use.
If you need to instrument and trace <<python-application,Python
-applications>> on openSUSE, you need to build and install
+applications>> on Yocto/OpenEmbedded, you need to build and install
LTTng-UST{nbsp}{revision} from source and pass the
`--enable-python-agent` option to the `configure` script.
====
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.8.tar.bz2 &&
tar -xf lttng-modules-latest-2.8.tar.bz2 &&
cd lttng-modules-2.8.* &&
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-ust/lttng-ust-latest-2.8.tar.bz2 &&
tar -xf lttng-ust-latest-2.8.tar.bz2 &&
cd lttng-ust-2.8.* &&
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.8.tar.bz2 &&
tar -xf lttng-tools-latest-2.8.tar.bz2 &&
cd lttng-tools-2.8.* &&
[[tracing-the-linux-kernel]]
=== Trace the Linux kernel
-The following command lines start with cmd:sudo because you need root
-privileges to trace the Linux kernel. You can avoid using cmd:sudo if
-your Unix user is a member of the <<tracing-group,tracing group>>.
+The following command lines start with the `#` prompt because you need
+root privileges to trace the Linux kernel. You can also trace the kernel
+as a regular user if your Unix user is a member of the
+<<tracing-group,tracing group>>.
. Create a <<tracing-session,tracing session>> which writes its traces
to dir:{/tmp/my-kernel-trace}:
--
[role="term"]
----
-sudo lttng create my-kernel-session --output=/tmp/my-kernel-trace
+# lttng create my-kernel-session --output=/tmp/my-kernel-trace
----
--
--
[role="term"]
----
-sudo lttng list --kernel
-sudo lttng list --kernel --syscall
+# lttng list --kernel
+# lttng list --kernel --syscall
----
--
--
[role="term"]
----
-sudo lttng enable-event --kernel sched_switch,sched_process_fork
-sudo lttng enable-event --kernel --syscall open,close
+# lttng enable-event --kernel sched_switch,sched_process_fork
+# lttng enable-event --kernel --syscall open,close
----
--
+
--
[role="term"]
----
-sudo lttng enable-event --kernel --all
+# lttng enable-event --kernel --all
----
--
--
[role="term"]
----
-sudo lttng start
+# lttng start
----
--
--
[role="term"]
----
-gcc -c -I. hello-tp.c
+$ gcc -c -I. hello-tp.c
----
--
--
[role="term"]
----
-gcc -c hello.c
+$ gcc -c hello.c
----
--
--
[role="term"]
----
-gcc -o hello hello.o hello-tp.o -llttng-ust -ldl
+$ gcc -o hello hello.o hello-tp.o -llttng-ust -ldl
----
--
--
[role="term"]
----
-./hello world and beyond
+$ ./hello world and beyond
----
--
+
--
[role="term"]
----
-lttng-sessiond --daemonize
+$ lttng-sessiond --daemonize
----
--
+
--
[role="term"]
----
-lttng list --userspace
+$ lttng list --userspace
----
--
+
--
[role="term"]
----
-lttng create my-user-space-session
+$ lttng create my-user-space-session
----
--
--
[role="term"]
----
-lttng enable-event --userspace hello_world:my_first_tracepoint
+$ lttng enable-event --userspace hello_world:my_first_tracepoint
----
--
--
[role="term"]
----
-lttng start
+$ lttng start
----
--
--
[role="term"]
----
-sudo lttng stop
-sudo lttng destroy
+$ lttng stop
+$ lttng destroy
----
--
+
[role="term"]
----
-babeltrace ~/lttng-traces/my-user-space-session*
+$ babeltrace ~/lttng-traces/my-user-space-session*
----
cmd:babeltrace finds all traces recursively within the given path and
[role="term"]
----
-babeltrace /tmp/my-kernel-trace | grep _switch
+$ babeltrace /tmp/my-kernel-trace | grep _switch
----
You can pipe the output of cmd:babeltrace into a tool like man:wc(1) to
[role="term"]
----
-babeltrace /tmp/my-kernel-trace | grep _open | wc --lines
+$ babeltrace /tmp/my-kernel-trace | grep _open | wc --lines
----
[role="term"]
----
-python3 top5proc.py /tmp/my-kernel-trace/kernel
+$ python3 top5proc.py /tmp/my-kernel-trace/kernel
----
Output example:
discard mode, the tracer only discards the event record that doesn't
fit.
-In discard mode, LTTng increments a count of lost event records when
-an event record is lost and saves this count to the trace. In
-overwrite mode, LTTng keeps no information when it overwrites a
-sub-buffer before consuming it.
+In discard mode, LTTng increments a count of lost event records when an
+event record is lost and saves this count to the trace. In overwrite
+mode, since LTTng 2.8, LTTng increments a count of lost sub-buffers when
+a sub-buffer is lost and saves this count to the trace. In this mode,
+the exact number of lost event records in those lost sub-buffers is not
+saved to the trace. Trace analyses can use the trace's saved discarded
+event record and sub-buffer counts to decide whether or not to perform
+the analyses even if trace data is known to be missing.
There are a few ways to decrease your probability of losing event
records.
* **High event throughput**: In general, prefer bigger sub-buffers to
lower the risk of losing event records.
+
-Having bigger sub-buffers also ensures a lower sub-buffer switching
-frequency.
+Having bigger sub-buffers also ensures a lower
+<<channel-switch-timer,sub-buffer switching frequency>>.
+
The number of sub-buffers is only meaningful if you create the channel
in overwrite mode: in this case, if a sub-buffer overwrite happens, the
An **event** is the consequence of the execution of an _instrumentation
point_, like a tracepoint that you manually place in some source code,
or a Linux kernel KProbe. An event is said to _occur_ at a specific
-time. Different actions can be taken upon the occurance of an event,
+time. Different actions can be taken upon the occurrence of an event,
like record the event's payload to a buffer.
An **event record** is the representation of an event in a sub-buffer. A
[role="term"]
----
-lttng <general options> <command> <command options>
+$ lttng <GENERAL OPTIONS> <COMMAND> <COMMAND OPTIONS>
----
The <<controlling-tracing,Tracing control>> section explores the
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o tpp.o -llttng-ust -ldl
+$ gcc -o app app.o tpp.o -llttng-ust -ldl
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -c tpp.c
+$ gcc -I. -c tpp.c
----
--
--
[role="term"]
----
-ar rcs tpp.a tpp.o
+$ ar rcs tpp.a tpp.o
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o tpp.a -llttng-ust -ldl
+$ gcc -o app app.o tpp.a -llttng-ust -ldl
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -ldl -L. -ltpp
+$ gcc -o app app.o -ldl -L. -ltpp
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -ldl
+$ gcc -o app app.o -ldl
----
--
--
[role="term"]
----
-LD_PRELOAD=./libtpp.so ./app
+$ LD_PRELOAD=./libtpp.so ./app
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -ldl
+$ gcc -o app app.o -ldl
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o tpp.o -llttng-ust -ldl
+$ gcc -shared -o libemon.so emon.o tpp.o -llttng-ust -ldl
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -L. -lemon
+$ gcc -o app app.o -L. -lemon
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o -ldl -L. -ltpp
+$ gcc -shared -o libemon.so emon.o -ldl -L. -ltpp
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -L. -lemon
+$ gcc -o app app.o -L. -lemon
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o -ldl
+$ gcc -shared -o libemon.so emon.o -ldl
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -L. -lemon
+$ gcc -o app app.o -L. -lemon
----
--
--
[role="term"]
----
-LD_PRELOAD=./libtpp.so ./app
+$ LD_PRELOAD=./libtpp.so ./app
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o -ldl
+$ gcc -shared -o libemon.so emon.o -ldl
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -L. -lemon
+$ gcc -o app app.o -L. -lemon
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o -ldl -L. -ltpp
+$ gcc -shared -o libemon.so emon.o -ldl -L. -ltpp
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -ldl -L. -lemon
+$ gcc -o app app.o -ldl -L. -lemon
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o -ldl
+$ gcc -shared -o libemon.so emon.o -ldl
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -ldl -L. -lemon
+$ gcc -o app app.o -ldl -L. -lemon
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o -ldl
+$ gcc -shared -o libemon.so emon.o -ldl
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o -L. -lemon
+$ gcc -o app app.o -L. -lemon
----
--
--
[role="term"]
----
-LD_PRELOAD=./libtpp.so ./app
+$ LD_PRELOAD=./libtpp.so ./app
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o
+$ gcc -shared -o libemon.so emon.o
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -o app app.o tpp.o -llttng-ust -ldl -L. -lemon
+$ gcc -o app app.o tpp.o -llttng-ust -ldl -L. -lemon
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
--
[role="term"]
----
-gcc -c app.c
+$ gcc -c app.c
----
--
--
[role="term"]
----
-gcc -Wl,--export-dynamic -o app app.o tpp.o \
+$ gcc -Wl,--export-dynamic -o app app.o tpp.o \
-llttng-ust -ldl
----
--
--
[role="term"]
----
-gcc -I. -fpic -c emon.c
+$ gcc -I. -fpic -c emon.c
----
--
--
[role="term"]
----
-gcc -shared -o libemon.so emon.o
+$ gcc -shared -o libemon.so emon.o
----
--
--
[role="term"]
----
-./app
+$ ./app
----
--
|====
[role="term"]
----
-LD_PRELOAD=liblttng-ust-fork.so ./my-app
+$ LD_PRELOAD=liblttng-ust-fork.so ./my-app
----
If your tracepoint provider package is
[role="term"]
----
-LD_PRELOAD=liblttng-ust-fork.so:/path/to/tp.so ./my-app
+$ LD_PRELOAD=liblttng-ust-fork.so:/path/to/tp.so ./my-app
----
[role="term"]
----
-gcc -o my-app my-app.o tp.o $(pkg-config --cflags --libs lttng-ust)
+$ gcc -o my-app my-app.o tp.o $(pkg-config --cflags --libs lttng-ust)
----
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/urcu/userspace-rcu-latest-0.9.tar.bz2 &&
tar -xf userspace-rcu-latest-0.9.tar.bz2 &&
cd userspace-rcu-0.9.* &&
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-ust/lttng-ust-latest-2.8.tar.bz2 &&
tar -xf lttng-ust-latest-2.8.tar.bz2 &&
cd lttng-ust-2.8.* &&
[role="term"]
----
-LDFLAGS='-L/usr/lib/i386-linux-gnu -L/usr/lib32'
+$ LDFLAGS='-L/usr/lib/i386-linux-gnu -L/usr/lib32'
----
====
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.8.tar.bz2 &&
tar -xf lttng-tools-latest-2.8.tar.bz2 &&
cd lttng-tools-2.8.* &&
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.8.tar.bz2 &&
tar -xf lttng-tools-latest-2.8.tar.bz2 &&
cd lttng-tools-2.8.* &&
--
[role="term"]
----
-gcc -m32 -c -I. hello-tp.c
-gcc -m32 -c hello.c
-gcc -m32 -o hello hello.o hello-tp.o \
+$ gcc -m32 -c -I. hello-tp.c
+$ gcc -m32 -c hello.c
+$ gcc -m32 -o hello hello.o hello-tp.o \
-L/usr/lib32 -L/usr/local/lib32 \
-Wl,-rpath,/usr/lib32,-rpath,/usr/local/lib32 \
-llttng-ust -ldl
--
[role="term"]
----
-gcc -o app app.c -llttng-ust
+$ gcc -o app app.c -llttng-ust
----
--
--
[role="term"]
----
-lttng enable-event --userspace 'lttng_ust_tracef:*'
+$ lttng enable-event --userspace 'lttng_ust_tracef:*'
----
--
--
[role="term"]
----
-gcc -o app app.c -llttng-ust
+$ gcc -o app app.c -llttng-ust
----
--
--
[role="term"]
----
-lttng enable-event --userspace 'lttng_ust_tracelog:*'
+$ lttng enable-event --userspace 'lttng_ust_tracelog:*'
--loglevel=TRACE_WARNING
----
--
--
[role="term"]
----
-lttng enable-event --userspace 'lttng_ust_tracelog:*'
+$ lttng enable-event --userspace 'lttng_ust_tracelog:*'
--loglevel-only=TRACE_INFO
----
--
--
[role="term"]
----
-LD_PRELOAD=liblttng-ust-libc-wrapper.so my-app
+$ LD_PRELOAD=liblttng-ust-libc-wrapper.so my-app
----
--
+
--
[role="term"]
----
-LD_PRELOAD=liblttng-ust-libc-wrapper.so:liblttng-ust-dl.so my-app
+$ LD_PRELOAD=liblttng-ust-libc-wrapper.so:liblttng-ust-dl.so my-app
----
--
[role="term"]
----
-javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java
+$ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java
----
<<creating-destroying-tracing-sessions,Create a tracing session>>,
[role="term"]
----
-lttng create
-lttng enable-event --jul jello
-lttng start
+$ lttng create
+$ lttng enable-event --jul jello
+$ lttng start
----
Run the compiled class:
[role="term"]
----
-java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test
+$ java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test
----
<<basic-tracing-session-control,Stop tracing>> and inspect the
[role="term"]
----
-lttng stop
-lttng view
+$ lttng stop
+$ lttng view
----
====
[role="term"]
----
-javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH Test.java
+$ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH Test.java
----
<<creating-destroying-tracing-sessions,Create a tracing session>>,
[role="term"]
----
-lttng create
-lttng enable-event --log4j jello
-lttng start
+$ lttng create
+$ lttng enable-event --log4j jello
+$ lttng start
----
Run the compiled class:
[role="term"]
----
-java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH:. Test
+$ java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-log4j.jar:$LOG4JPATH:. Test
----
<<basic-tracing-session-control,Stop tracing>> and inspect the
[role="term"]
----
-lttng stop
-lttng view
+$ lttng stop
+$ lttng view
----
====
[role="term"]
----
-javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java
+$ javac -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar Test.java
----
<<creating-destroying-tracing-sessions,Create a tracing session>>
[role="term"]
----
-lttng create
-lttng enable-event --jul jello
+$ lttng create
+$ lttng enable-event --jul jello
----
<<adding-context,Add the application-specific context fields>> to the
[role="term"]
----
-lttng add-context --jul --type='$app.myRetriever:intCtx'
-lttng add-context --jul --type='$app.myRetriever:strContext'
+$ lttng add-context --jul --type='$app.myRetriever:intCtx'
+$ lttng add-context --jul --type='$app.myRetriever:strContext'
----
<<basic-tracing-session-control,Start tracing>>:
[role="term"]
----
-lttng start
+$ lttng start
----
Run the compiled class:
[role="term"]
----
-java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test
+$ java -cp /usr/share/java/jarpath/lttng-ust-agent-common.jar:/usr/share/java/jarpath/lttng-ust-agent-jul.jar:. Test
----
<<basic-tracing-session-control,Stop tracing>> and inspect the
[role="term"]
----
-lttng stop
-lttng view
+$ lttng stop
+$ lttng view
----
====
[role="term"]
----
-lttng create
-lttng enable-event --python my-logger
-lttng start
+$ lttng create
+$ lttng enable-event --python my-logger
+$ lttng start
----
Run the Python script:
[role="term"]
----
-python test.py
+$ python test.py
----
<<basic-tracing-session-control,Stop tracing>> and inspect the recorded
[role="term"]
----
-lttng stop
-lttng view
+$ lttng stop
+$ lttng view
----
====
[role="term"]
----
-echo "Some message, some $variable" > /proc/lttng-logger
+$ echo "Some message, some $variable" > /proc/lttng-logger
----
Any event that the LTTng logger emits is named `lttng_logger` and
[role="term"]
----
-lttng create
-lttng enable-event --kernel lttng_logger
-lttng start
+$ lttng create
+$ lttng enable-event --kernel lttng_logger
+$ lttng start
----
Run the Bash script:
[role="term"]
----
-bash test.bash
+$ bash test.bash
----
<<basic-tracing-session-control,Stop tracing>> and inspect the recorded
[role="term"]
----
-lttng stop
-lttng view
+$ lttng stop
+$ lttng view
----
====
--
[role="term"]
----
-cd $(mktemp -d) &&
+$ cd $(mktemp -d) &&
wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.8.tar.bz2 &&
tar -xf lttng-modules-latest-2.8.tar.bz2 &&
cd lttng-modules-2.8.*
----
--
-. Edit path:{probes/Makefile} and add your new kernel module object
+. Edit path:{probes/KBuild} and add your new kernel module object
next to the existing ones:
+
--
[source,make]
-.path:{probes/Makefile}
+.path:{probes/KBuild}
----
# ...
--
[role="term"]
----
-make KERNELDIR=/path/to/linux
-sudo make modules_install
+$ make KERNELDIR=/path/to/linux
+# make modules_install && depmod -a
----
--
+
====
[role="term"]
----
-sudo lttng-sessiond --extra-kmod-probes=my_subsys,usb
+# lttng-sessiond --extra-kmod-probes=my_subsys,usb
----
====
--
====
[role="term"]
----
-sudo lttng-sessiond --kmod-probes=my_subsys,usb
+# lttng-sessiond --kmod-probes=my_subsys,usb
----
====
--
--
[role="term"]
----
-lsmod | grep lttng_probe_usb
+$ lsmod | grep lttng_probe_usb
----
--
--
[role="term"]
----
-sudo pkill lttng-sessiond
+# pkill lttng-sessiond
----
--
+
--
[role="term"]
----
-lttng-sessiond --daemonize
+$ lttng-sessiond --daemonize
----
--
--
[role="term"]
----
-sudo lttng-sessiond --daemonize
+# lttng-sessiond --daemonize
----
--
--
[role="term"]
----
-lttng create
+$ lttng create
----
--
--
[role="term"]
----
-lttng create my-session
+$ lttng create my-session
----
--
+
--
[role="term"]
----
-lttng create --output=/tmp/some-directory my-session
+$ lttng create my-session --output=/tmp/some-directory
----
--
--
[role="term"]
----
-lttng list
+$ lttng list
----
--
--
[role="term"]
----
-lttng set-session new-session
+$ lttng set-session new-session
----
--
+
--
[role="term"]
----
-lttng destroy
+$ lttng destroy
----
--
====
[role="term"]
----
-lttng list --userspace
+$ lttng list --userspace
----
====
====
[role="term"]
----
-lttng list --kernel --syscall
+$ lttng list --kernel --syscall
----
====
====
[role="term"]
----
-lttng enable-event --kernel sched_switch
+$ lttng enable-event --kernel sched_switch
----
====
====
[role="term"]
----
-lttng enable-event --kernel --syscall open,write,read,close
+$ lttng enable-event --kernel --syscall open,write,read,close
----
====
====
[role="term"]
----
-lttng enable-event --kernel sched_switch --filter='prev_comm == "bash"'
+$ lttng enable-event --kernel sched_switch --filter='prev_comm == "bash"'
----
[role="term"]
----
-lttng enable-event --kernel --all \
+$ lttng enable-event --kernel --all \
--filter='$ctx.tid == 1988 || $ctx.tid == 1534'
----
[role="term"]
----
-lttng enable-event --jul my_logger \
+$ lttng enable-event --jul my_logger \
--filter='$app.retriever:cur_msg_id > 3'
----
====
[role="term"]
----
-lttng enable-event --userspace my_app:'*' --loglevel=TRACE_INFO
+$ lttng enable-event --userspace my_app:'*' --loglevel=TRACE_INFO
----
IMPORTANT: Make sure to always quote the wildcard character when you
====
[role="term"]
----
-lttng enable-event --python my-app.'*' \
+$ lttng enable-event --python my-app.'*' \
--exclude='my-app.module,my-app.hello'
----
====
====
[role="term"]
----
-lttng enable-event --log4j --all --loglevel-only=LOG4J_WARN
+$ lttng enable-event --log4j --all --loglevel-only=LOG4J_WARN
----
====
====
[role="term"]
----
-lttng enable-event --userspace my_app:my_tracepoint --channel=my-channel
+$ lttng enable-event --userspace my_app:my_tracepoint --channel=my-channel
----
====
[role="term"]
----
-lttng enable-event --userspace my_app:my_tracepoint
-lttng enable-event --userspace my_app:my_tracepoint \
+$ lttng enable-event --userspace my_app:my_tracepoint
+$ lttng enable-event --userspace my_app:my_tracepoint \
--loglevel=TRACE_INFO
----
====
[role="term"]
----
-lttng disable-event --python my-logger
+$ lttng disable-event --python my-logger
----
====
====
[role="term"]
----
-lttng disable-event --jul '*'
+$ lttng disable-event --jul '*'
----
====
[role="term"]
----
-lttng disable-event --jul --all-events
+$ lttng disable-event --jul --all-events
----
====
--
[role="term"]
----
-lttng status
+$ lttng status
----
--
+
--
[role="term"]
----
-lttng list my-session
+$ lttng list my-session
----
--
+
--
[role="term"]
----
-lttng start
+$ lttng start
----
--
--
[role="term"]
----
-lttng stop
+$ lttng stop
----
--
+
====
[role="term"]
----
-lttng enable-channel --kernel my-channel
+$ lttng enable-channel --kernel my-channel
----
====
====
[role="term"]
----
-lttng enable-channel --userspace --num-subbuf=4 --subbuf-size=1M \
+$ lttng enable-channel --userspace --num-subbuf=4 --subbuf-size=1M \
--buffers-pid my-channel
----
====
====
[role="term"]
----
-lttng enable-channel --kernel --tracefile-count=8 \
+$ lttng enable-channel --kernel --tracefile-count=8 \
--tracefile-size=4194304 my-channel
----
====
====
[role="term"]
----
-lttng enable-channel --userspace --overwrite my-channel
+$ lttng enable-channel --userspace --overwrite my-channel
----
====
[role="term"]
----
-lttng enable-event --userspace --channel=my-channel app:tp
-lttng enable-event --userspace --channel=other-channel app:tp
+$ lttng enable-event --userspace --channel=my-channel app:tp
+$ lttng enable-event --userspace --channel=other-channel app:tp
----
If both channels are enabled, when a tracepoint named `app:tp` is
====
[role="term"]
----
-lttng disable-channel --kernel my-channel
+$ lttng disable-channel --kernel my-channel
----
====
[role="term"]
----
-lttng add-context --userspace --type=vpid --type=perf:thread:cpu-cycles
+$ lttng add-context --userspace --type=vpid --type=perf:thread:cpu-cycles
----
====
[role="term"]
----
-lttng add-context --kernel --channel=my-channel --type=tid
+$ lttng add-context --kernel --channel=my-channel --type=tid
----
====
[role="term"]
----
-lttng add-context --kernel --channel=my-channel \
+$ lttng add-context --kernel --channel=my-channel \
--type='$app:retriever:cur_msg_id'
----
[role="term"]
----
-lttng track --pid=3,4,7,10,13
+$ lttng track --pid=3,4,7,10,13
----
the whitelist is:
[role="term"]
----
-lttng track --pid=1,15,16
+$ lttng track --pid=1,15,16
----
The result is:
[role="term"]
----
-lttng untrack --pid=3,7,10,13
+$ lttng untrack --pid=3,7,10,13
----
leads to this whitelist:
[role="term"]
----
-lttng track --pid --all
+$ lttng track --pid --all
----
The result is, again:
[role="term"]
----
-lttng untrack --pid --all
+$ lttng untrack --pid --all
----
gives:
[role="term"]
----
-lttng track --pid=6,11
+$ lttng track --pid=6,11
----
Result:
--
[role="term"]
----
-lttng save my-session
+$ lttng save my-session
----
--
+
--
[role="term"]
----
-lttng load my-session
+$ lttng load my-session
----
--
+
--
[role="term"]
----
-lttng-relayd
+$ lttng-relayd
----
--
--
[role="term"]
----
-lttng create my-session --set-url=net://remote-system
+$ lttng create my-session --set-url=net://remote-system
----
--
+
--
[role="term"]
----
-lttng create --live my-session
+$ lttng create my-session --live
----
--
+
--
[role="term"]
----
-babeltrace --input-format=lttng-live net://localhost/host/hostname/my-session
+$ babeltrace --input-format=lttng-live
+ net://localhost/host/hostname/my-session
----
--
+
[role="term"]
----
-babeltrace --input-format=lttng-live net://localhost
+$ babeltrace --input-format=lttng-live net://localhost
----
You can start the relay daemon on another system. In this case, you need
--
[role="term"]
----
-lttng create --snapshot my-session
+$ lttng create my-session --snapshot
----
--
+
--
[role="term"]
----
-lttng snapshot record --name=my-first-snapshot
+$ lttng snapshot record --name=my-first-snapshot
----
--
+
[role="term"]
----
-lttng --mi=xml enable-event --kernel --syscall open
+$ lttng --mi=xml enable-event --kernel --syscall open
----
A schema definition (XSD) is
--
[role="term"]
----
-lttng metadata regenerate
+$ lttng metadata regenerate
----
--
--
[role="term"]
----
-lttng create --shm-path=/path/to/shm
+$ lttng create my-session --shm-path=/path/to/shm
----
--
--
[role="term"]
----
-lttng-crash /path/to/shm
+$ lttng-crash /path/to/shm
----
--
--
[role="term"]
----
-lttng-crash --extract=/path/to/trace /path/to/shm
+$ lttng-crash --extract=/path/to/trace /path/to/shm
----
--
or a Linux kernel KProbe.
+
An event is said to _occur_ at a specific time. Different actions can
-be taken upon the occurance of an event, like record the event's payload
+be taken upon the occurrence of an event, like record the event's payload
to a sub-buffer.
<<channel-overwrite-mode-vs-discard-mode,event loss mode>>::
projects / lttng-docs.git / blobdiff