The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.10, 22 January 2018
+v2.10, 18 October 2019
include::../common/copyright.txt[]
applications.
[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 22 January 2018.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 18 October 2019.
|====
-|Distribution |Available in releases |Alternatives
+|Distribution |Available in releases
|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.9#doc-ubuntu[LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_ and Ubuntu{nbsp}17.10 _Artful Aardvark_].
+|xref:ubuntu[Ubuntu{nbsp}18.04 _Bionic Beaver_,
+Ubuntu{nbsp}19.04 _Disco Dingo_, and
+Ubuntu{nbsp}19.10 _Eoan Ermine_].
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Ubuntu releases.
+Ubuntu{nbsp}16.04 _Xenial Xerus_:
+<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
|https://getfedora.org/[Fedora]
-|<<fedora,Fedora{nbsp}27>>.
-|link:/docs/v2.9#doc-fedora[LTTng{nbsp}2.9 for Fedora{nbsp}26].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Fedora releases.
+|xref:fedora[Fedora{nbsp}29, Fedora{nbsp}30, Fedora{nbsp}31,
+and Fedora{nbsp}32].
|https://www.debian.org/[Debian]
-|<<debian,Debian "buster" (testing) and Debian "sid" (unstable)>>.
-|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch" (stable)].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|https://www.archlinux.org/[Arch Linux]
-|<<arch-linux,Current Arch Linux build>>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|<<debian,Debian "buster" (stable) and Debian "bullseye" (testing)>>.
|https://alpinelinux.org/[Alpine Linux]
-|<<alpine-linux,Alpine Linux{nbsp}3.7 and Alpine Linux{nbsp}"edge">>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|xref:alpine-linux[Alpine Linux{nbsp}3.7, Alpine Linux{nbsp}3.8,
+Alpine Linux{nbsp}3.9, and Alpine Linux{nbsp}3.10].
+
+|https://www.opensuse.org/[openSUSE]
+|<<opensuse,openSUSE Leap{nbsp}15.1>>.
|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES]
|See http://packages.efficios.com/[EfficiOS Enterprise Packages].
-|
|https://buildroot.org/[Buildroot]
-|_Not available_
-|link:/docs/v2.9#doc-buildroot[LTTng{nbsp}2.9 for 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>>.
+|xref:buildroot[Buildroot{nbsp}2018.02, Buildroot{nbsp}2018.05,
+Buildroot{nbsp}2018.08, Buildroot{nbsp}2018.11, Buildroot{nbsp}2019.02,
+Buildroot{nbsp}2018.05, Buildroot{nbsp}2018.08, and
+Buildroot{nbsp}2018.11].
|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and
https://www.yoctoproject.org/[Yocto]
-|_Not available_
-|link:/docs/v2.9#doc-oe-yocto[LTTng{nbsp}2.9 for Yocto Project{nbsp}2.3 _Pyro_
-and Yocto Project{nbsp}2.4 _Rocko_]
-(`openembedded-core` layer).
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|<<oe-yocto,Yocto Project{nbsp}2.7 _Warrior_ and
+Yocto Project{nbsp}3.0 _Zeus_>>.
|====
[[ubuntu]]
=== [[ubuntu-official-repositories]]Ubuntu
+LTTng{nbsp}{revision} is available on:
+
+* Ubuntu{nbsp}18.04 _Bionic Beaver_
+* Ubuntu{nbsp}19.04 _Disco Dingo_
+* Ubuntu{nbsp}19.10 _Eoan Ermine_
+
+For other releases of Ubuntu, <<ubuntu-ppa,use the LTTng
+Stable{nbsp}{revision} PPA>>.
+
+To install LTTng{nbsp}{revision} on Ubuntu{nbsp}18.04 _Bionic Beaver_,
+Ubuntu{nbsp}19.04 _Disco Dingo_, or
+Ubuntu{nbsp}19.10 _Eoan Ermine_:
+
+. 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
+----
+--
+
+. **If you need to instrument and trace
+ <<java-application,Java applications>>**, install the LTTng-UST
+ Java agent:
++
+--
+[role="term"]
+----
+# apt-get install liblttng-ust-agent-java
+----
+--
+
+. **If you need to instrument and trace
+ <<python-application,Python{nbsp}3 applications>>**, install the
+ LTTng-UST Python agent:
++
+--
+[role="term"]
+----
+# apt-get install python3-lttngust
+----
+--
+
+
[[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} packages for Ubuntu{nbsp}18.04 _Bionic Beaver_.
To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA:
[[fedora]]
=== Fedora
-To install LTTng{nbsp}{revision} on Fedora{nbsp}27:
+To install LTTng{nbsp}{revision} on Fedora{nbsp}29, Fedora{nbsp}30,
+Fedora{nbsp}31, or Fedora{nbsp}32:
. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision}
packages:
[[debian]]
=== Debian
-To install LTTng{nbsp}{revision} on Debian "buster" (testing)
-or Debian "sid" (unstable):
+To install LTTng{nbsp}{revision} on Debian "buster" (stable) or
+Debian "bullseye" (testing):
. Install the main LTTng{nbsp}{revision} packages:
+
--
-[[arch-linux]]
-=== Arch Linux
-
-LTTng-UST{nbsp}{revision} is available in Arch Linux's _Community_
-repository, while LTTng-tools{nbsp}{revision} and
-LTTng-modules{nbsp}{revision} are available in the
-https://aur.archlinux.org/[AUR].
+[[alpine-linux]]
+=== Alpine Linux
-To install LTTng{nbsp}{revision} on Arch Linux, using
-https://github.com/rmarquis/pacaur[pacaur] for the AUR packages:
+To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
+Alpine Linux{nbsp}3.7, Alpine Linux{nbsp}3.8, Alpine Linux{nbsp}3.9, or
+Alpine Linux{nbsp}3.10:
-. Install the main LTTng{nbsp}{revision} packages:
+. Add the LTTng packages:
+
--
[role="term"]
----
-# pacman -Sy lttng-ust
-$ pacaur -Sy lttng-tools
-$ pacaur -Sy lttng-modules
+# apk add lttng-tools
+# apk add lttng-ust-dev
----
--
-. **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"]
----
-# pacman -Sy python-lttngust
-# pacman -Sy python2-lttngust
+$ cd $(mktemp -d) &&
+wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.10.tar.bz2 &&
+tar -xf lttng-modules-latest-2.10.tar.bz2 &&
+cd lttng-modules-2.10.* &&
+make &&
+sudo make modules_install &&
+sudo depmod -a
----
--
-[[alpine-linux]]
-=== Alpine Linux
+[[opensuse]]
+=== noch:{openSUSE}
-To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
-Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}"edge":
-
-. **If you're installing for Alpine Linux{nbsp}"edge"**, make sure your
- system is https://wiki.alpinelinux.org/wiki/Edge[configured for
- "edge"].
-. **If you're installing for Alpine Linux{nbsp}"edge"**, enable the _testing_
- repository by uncommenting the corresponding line in
- path:{/etc/apk/repositories}.
-. Add the LTTng packages:
+To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}15.1:
+
+* Install the main LTTng{nbsp}{revision} packages:
+
--
[role="term"]
----
-# apk add lttng-tools
-# apk add lttng-ust-dev
+sudo zypper install lttng-tools
+sudo zypper install lttng-modules
+sudo zypper install lttng-ust-devel
----
--
-To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support)
-on Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}"edge":
+[IMPORTANT]
+.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
+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
+LTTng-UST{nbsp}{revision} from source and pass the
+`--enable-python-agent` option to the `configure` script.
+====
+
-. Add the vanilla Linux kernel:
+[[enterprise-distributions]]
+=== RHEL, SUSE, and other enterprise distributions
+
+To install LTTng on enterprise Linux distributions, such as Red Hat
+Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SUSE), please
+see http://packages.efficios.com/[EfficiOS Enterprise Packages].
+
+
+[[buildroot]]
+=== Buildroot
+
+To install LTTng{nbsp}{revision} on Buildroot{nbsp}2018.02,
+Buildroot{nbsp}2018.05, Buildroot{nbsp}2018.08,
+Buildroot{nbsp}2018.11, Buildroot{nbsp}2019.02,
+Buildroot{nbsp}2019.05, Buildroot{nbsp}2019.08, or
+Buildroot{nbsp}2019.11:
+
+. Launch the Buildroot configuration tool:
+
--
[role="term"]
----
-# apk add linux-vanilla linux-vanilla-dev
+$ make menuconfig
----
--
-. Reboot with the vanilla Linux kernel.
-. Download, build, and install the latest LTTng-modules{nbsp}{revision}:
-+
---
-[role="term"]
+. In **Kernel**, check **Linux kernel**.
+. In **Toolchain**, check **Enable WCHAR support**.
+. In **Target packages**{nbsp}→ **Debugging, profiling and benchmark**,
+ check **lttng-modules** and **lttng-tools**.
+. In **Target packages**{nbsp}→ **Libraries**{nbsp}→
+ **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.7 _Warrior_ and
+Yocto Project{nbsp}3.0 _Zeus_ 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}:
+
----
-$ cd $(mktemp -d) &&
-wget http://lttng.org/files/lttng-modules/lttng-modules-latest-2.10.tar.bz2 &&
-tar -xf lttng-modules-latest-2.10.tar.bz2 &&
-cd lttng-modules-2.10.* &&
-make &&
-sudo make modules_install &&
-sudo depmod -a
+IMAGE_INSTALL_append = " lttng-tools lttng-modules lttng-ust"
----
---
+If you use Hob:
-[[enterprise-distributions]]
-=== RHEL, SUSE, and other enterprise distributions
+. Select a machine and an image recipe.
+. Click **Edit image recipe**.
+. Under the **All recipes** tab, search for **lttng**.
+. Check the desired LTTng recipes.
-To install LTTng on enterprise Linux distributions, such as Red Hat
-Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SUSE), please
-see http://packages.efficios.com/[EfficiOS Enterprise Packages].
+[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]]
. Do some operation on your system for a few seconds. For example,
load a website, or list the files of a directory.
-. <<basic-tracing-session-control,Stop tracing>> and destroy the
+. <<creating-destroying-tracing-sessions,Destroy>> the current
tracing session:
+
--
[role="term"]
----
-# lttng stop
# lttng destroy
----
--
+
The man:lttng-destroy(1) command does not destroy the trace data; it
only destroys the state of the tracing session.
++
+The man:lttng-destroy(1) command also runs the man:lttng-stop(1) command
+implicitly (see <<basic-tracing-session-control,Start and stop a tracing
+session>>). You need to stop tracing to make LTTng flush the remaining
+trace data and make the trace readable.
. For the sake of this example, make the recorded trace accessible to
the non-root users:
. Go back to the running `hello` application and press Enter. The
program executes all `tracepoint()` instrumentation points and exits.
-. <<basic-tracing-session-control,Stop tracing>> and destroy the
+. <<creating-destroying-tracing-sessions,Destroy>> the current
tracing session:
+
--
[role="term"]
----
-$ lttng stop
$ lttng destroy
----
--
+
The man:lttng-destroy(1) command does not destroy the trace data; it
only destroys the state of the tracing session.
++
+The man:lttng-destroy(1) command also runs the man:lttng-stop(1) command
+implicitly (see <<basic-tracing-session-control,Start and stop a tracing
+session>>). You need to stop tracing to make LTTng flush the remaining
+trace data and make the trace readable.
By default, LTTng saves the traces in
+$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+,
There are a few ways to decrease your probability of losing event
records.
<<channel-subbuf-size-vs-subbuf-count,Sub-buffer count and size>> shows
-how you can fine-une the sub-buffer count and size of a channel to
+how you can fine-tune the sub-buffer count and size of a channel to
virtually stop losing event records, though at the cost of greater
memory usage.
----
--
+The man:lttng-destroy(1) command also runs the man:lttng-stop(1)
+command implicitly (see <<basic-tracing-session-control,Start and stop a
+tracing session>>). You need to stop tracing to make LTTng flush the
+remaining trace data and make the trace readable.
+
[[list-instrumentation-points]]
=== List the available instrumentation points
man:lttng-start(1), warnings are printed when you run the
man:lttng-stop(1) command.
+IMPORTANT: You need to stop tracing to make LTTng flush the remaining
+trace data and make the trace readable. Note that the
+man:lttng-destroy(1) command (see
+<<creating-destroying-tracing-sessions,Create and destroy a tracing
+session>>) also runs the man:lttng-stop(1) command implicitly.
+
[[enabling-disabling-channels]]
=== Create a channel
projects / lttng-docs.git / blobdiff