The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.9, 14 March 2017
+v2.9, 22 January 2018
include::../common/copyright.txt[]
+include::../common/warning-not-maintained.txt[]
+
+
include::../common/welcome.txt[]
applications.
[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 14 March 2017.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 22 January 2018.
|====
|Distribution |Available in releases |Alternatives
|https://www.ubuntu.com/[Ubuntu]
-|Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_:
-<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
-|link:/docs/v2.8#doc-ubuntu[LTTng{nbsp}2.8 for Ubuntu{nbsp}16.10 _Yakkety Yak_].
+|<<ubuntu,Ubuntu{nbsp}17.04 _Zesty Zapus_ and Ubuntu{nbsp}17.10 _Artful Aardvark_>>.
-LTTng{nbsp}{revision} for Ubuntu{nbsp}17.04 _Zesty Zapus_ (not released
-yet).
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+Ubuntu{nbsp}14.04 _Trusty Tahr_ and Ubuntu{nbsp}16.04 _Xenial Xerus_:
+<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other Ubuntu releases.
|https://getfedora.org/[Fedora]
-|_Not available_
-|link:/docs/v2.8#doc-fedora[LTTng{nbsp}2.8 for Fedora 25].
+|<<fedora,Fedora{nbsp}26>>.
+|link:/docs/v2.10#doc-fedora[LTTng{nbsp}2.10 for Fedora{nbsp}27].
-<<building-from-source,Build LTTng-modules{nbsp}{revision} from
-source>>.
+<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+other Fedora releases.
|https://www.debian.org/[Debian]
-|<<debian,Debian "stretch" (testing) and Debian "sid" (unstable)>>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+|<<debian,Debian "stretch" (stable)>>.
+|link:/docs/v2.10#doc-debian[LTTng{nbsp}2.10 for Debian "buster" (testing)
+and Debian "sid" (unstable)].
+
+
+<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other Debian releases.
-|https://www.opensuse.org/[openSUSE]
+|https://www.archlinux.org/[Arch Linux]
|_Not available_
-|<<building-from-source,Build LTTng-modules{nbsp}{revision} from
-source>>.
+|link:/docs/v2.10#doc-arch-linux[LTTng{nbsp}2.10 for the current Arch Linux build].
-|https://www.archlinux.org/[Arch Linux]
-|<<arch-linux,Latest AUR packages>>.
-|
+<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|https://alpinelinux.org/[Alpine Linux]
-|<<alpine-linux,Alpine Linux "edge">>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Alpine Linux releases.
+|_Not available_
+|link:/docs/v2.10#doc-alpine-linux[LTTng{nbsp}2.10 for Alpine Linux{nbsp}3.7
+and Alpine Linux{nbsp}"edge"].
+
+<<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 2017.02>>.
-|link:/docs/v2.8#doc-buildroot[LTTng{nbsp}2.8 for Buildroot 2016.11].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+|<<"buildroot", "Buildroot{nbsp}2017.02, Buildroot{nbsp}2017.05, Buildroot{nbsp}2017.08, and Buildroot{nbsp}2017.11">>.
+|<<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]
-|_Not available_
-|link:/docs/v2.8#doc-oe-yocto[LTTng{nbsp}2.8 for Yocto Project{nbsp}2.2 _Morty_]
+|<<oe-yocto,Yocto Project{nbsp}2.3 _Pyro_ and Yocto Project{nbsp}2.4 _Rocko_>>
(`openembedded-core` layer).
-
-LTTng{nbsp}{revision} 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.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+other Yocto/OpenEmbedded releases.
|====
[[ubuntu]]
=== [[ubuntu-official-repositories]]Ubuntu
-[[ubuntu-ppa]]
-==== noch:{LTTng} Stable {revision} PPA
-
-The https://launchpad.net/~lttng/+archive/ubuntu/stable-{revision}[LTTng
-Stable{nbsp}{revision} PPA] offers the latest stable
-LTTng{nbsp}{revision} packages for:
-
-* Ubuntu{nbsp}14.04 _Trusty Tahr_
-* Ubuntu{nbsp}16.04 _Xenial Xerus_
+LTTng{nbsp}{revision} is available on Ubuntu{nbsp}17.04 _Zesty Zapus_
+and Ubuntu{nbsp}17.10 _Artful Aardvark_. For previous releases of
+Ubuntu, <<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
-To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA:
-
-. Add the LTTng Stable{nbsp}{revision} PPA repository and update the
- list of packages:
-+
---
-[role="term"]
-----
-# apt-add-repository ppa:lttng/stable-2.9
-# apt-get update
-----
---
+To install LTTng{nbsp}{revision} on Ubuntu{nbsp}17.04 _Zesty Zapus_:
. Install the main LTTng{nbsp}{revision} packages:
+
--
-[[debian]]
-=== Debian
+[[ubuntu-ppa]]
+==== noch:{LTTng} Stable {revision} PPA
+
+The https://launchpad.net/~lttng/+archive/ubuntu/stable-{revision}[LTTng
+Stable{nbsp}{revision} PPA] offers the latest stable
+LTTng{nbsp}{revision} packages for:
-To install LTTng{nbsp}{revision} on Debian "stretch" (testing) or
-Debian "sid" (unstable):
+* Ubuntu{nbsp}14.04 _Trusty Tahr_
+* Ubuntu{nbsp}16.04 _Xenial Xerus_
+
+To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA:
+
+. Add the LTTng Stable{nbsp}{revision} PPA repository and update the
+ list of packages:
++
+--
+[role="term"]
+----
+# apt-add-repository ppa:lttng/stable-2.9
+# apt-get update
+----
+--
. Install the main LTTng{nbsp}{revision} packages:
+
--
[role="term"]
----
+# apt-get install lttng-tools
# apt-get install lttng-modules-dkms
# apt-get install liblttng-ust-dev
-# apt-get install lttng-tools
----
--
-. **If you need to instrument and trace <<java-application,Java
- applications>>**, install the LTTng-UST Java agent:
+. **If you need to instrument and trace
+ <<java-application,Java applications>>**, install the LTTng-UST
+ Java agent:
+
--
[role="term"]
----
--
-. **If you need to instrument and trace <<python-application,Python
- applications>>**, install the LTTng-UST Python agent:
+. **If you need to instrument and trace
+ <<python-application,Python{nbsp}3 applications>>**, install the
+ LTTng-UST Python agent:
+
--
[role="term"]
--
-[[arch-linux]]
-=== Arch Linux
+[[fedora]]
+=== Fedora
-To install LTTng{nbsp}{revision} on Arch Linux using
-https://archlinux.fr/yaourt-en[Yaourt]:
+To install LTTng{nbsp}{revision} on Fedora{nbsp}26:
-. Install the main LTTng{nbsp}{revision} packages:
+. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision}
+ packages:
+
--
[role="term"]
----
-$ yaourt -S lttng-tools
-$ yaourt -S lttng-ust
-$ yaourt -S lttng-modules
+# yum install lttng-tools
+# yum install lttng-ust
----
--
-. **If you need to instrument and trace <<python-application,Python
- applications>>**, install the LTTng-UST Python agent:
+. Download, build, and install the latest LTTng-modules{nbsp}{revision}:
+
--
[role="term"]
----
-$ yaourt -S python-lttngust
-$ yaourt -S python2-lttngust
+$ cd $(mktemp -d) &&
+wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.9.tar.bz2 &&
+tar -xf lttng-modules-latest-2.9.tar.bz2 &&
+cd lttng-modules-2.9.* &&
+make &&
+sudo make modules_install &&
+sudo depmod -a
----
--
+[IMPORTANT]
+.Java and Python application instrumentation and tracing
+====
+If you need to instrument and trace <<java-application,Java
+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 Fedora, you need to build and install
+LTTng-UST{nbsp}{revision} from source and pass the
+`--enable-python-agent` option to the `configure` script.
+====
-[[alpine-linux]]
-=== Alpine Linux
-To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
-Alpine Linux "edge":
+[[debian]]
+=== Debian
+
+To install LTTng{nbsp}{revision} on Debian "stretch" (stable):
-. 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:
+. Install the main LTTng{nbsp}{revision} packages:
+
--
[role="term"]
----
-# apk add lttng-tools
-# apk add lttng-ust-dev
+# apt-get install lttng-modules-dkms
+# apt-get install liblttng-ust-dev
+# apt-get install lttng-tools
----
--
-To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support)
-on Alpine Linux "edge":
-
-. Add the vanilla Linux kernel:
+. **If you need to instrument and trace <<java-application,Java
+ applications>>**, install the LTTng-UST Java agent:
+
--
[role="term"]
----
-# apk add linux-vanilla linux-vanilla-dev
+# apt-get install liblttng-ust-agent-java
----
--
-. Reboot with the vanilla Linux kernel.
-. Download, build, and install the latest LTTng-modules{nbsp}{revision}:
+. **If you need to instrument and trace <<python-application,Python
+ applications>>**, install the LTTng-UST Python agent:
+
--
[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
+# apt-get install python3-lttngust
----
--
[[buildroot]]
=== Buildroot
-To install LTTng{nbsp}{revision} on Buildroot{nbsp}2017.02:
+To install LTTng{nbsp}{revision} on Buildroot{nbsp}2017.02,
+Buildroot{nbsp}2017.05, Buildroot{nbsp}2017.08, or
+Buildroot{nbsp}2017.11:
. Launch the Buildroot configuration tool:
+
**Other**, check **lttng-libust**.
+[[oe-yocto]]
+=== OpenEmbedded and Yocto
+
+LTTng{nbsp}{revision} recipes are available in the
+http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/[`openembedded-core`]
+layer for Yocto Project{nbsp}2.3 _Pyro_ and Yocto Project{nbsp}2.4 _Rocko_
+under the following names:
+
+* `lttng-tools`
+* `lttng-modules`
+* `lttng-ust`
+
+With BitBake, the simplest way to include LTTng recipes in your target
+image is to add them to `IMAGE_INSTALL_append` in path:{conf/local.conf}:
+
+----
+IMAGE_INSTALL_append = " lttng-tools lttng-modules lttng-ust"
+----
+
+If you use Hob:
+
+. Select a machine and an image recipe.
+. Click **Edit image recipe**.
+. Under the **All recipes** tab, search for **lttng**.
+. Check the desired LTTng recipes.
+
+[IMPORTANT]
+.Java and Python application instrumentation and tracing
+====
+If you need to instrument and trace <<java-application,Java
+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 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.
+====
+
+
[[building-from-source]]
=== Build from source
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.
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
* **LTTng-tools**: Libraries and command-line interface to
control tracing sessions.
** <<lttng-sessiond,Session daemon>> (man:lttng-sessiond(8)).
-** <<lttng-consumerd,Consumer daemon>> (man:lttng-consumerd(8)).
+** <<lttng-consumerd,Consumer daemon>> (cmd:lttng-consumerd).
** <<lttng-relayd,Relay daemon>> (man:lttng-relayd(8)).
** <<liblttng-ctl-lttng,Tracing control library>> (`liblttng-ctl`).
** <<lttng-cli,Tracing control command-line tool>> (man:lttng(1)).
.The consumer daemon.
image::plumbing-consumerd.png[]
-The _consumer daemon_, man:lttng-consumerd(8), is a daemon which shares
+The _consumer daemon_, cmd:lttng-consumerd, is a daemon which shares
ring buffers with user applications or with the LTTng kernel modules to
collect trace data and send it to some location (on disk or to a
<<lttng-relayd,relay daemon>> over the network). The consumer daemon
.LTTng-UST Java agent imported by a Java application.
image::java-app.png[]
-Note that the methods described below are new in LTTng{nbsp}{revision}.
+Note that the methods described below are new in LTTng{nbsp}2.8.
Previous LTTng versions use another technique.
NOTE: We use http://openjdk.java.net/[OpenJDK]{nbsp}8 for development
----
--
-. 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}
----
# ...
.PIDs 3, 7, 10, and 13 are removed from the whitelist.
image::track-1-4-15-16.png[]
-LTTng can track all possible PIDs again using the opt:track(1):--all
-option:
+LTTng can track all possible PIDs again using the
+opt:lttng-track(1):--all option:
[role="term"]
----
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