The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.10, 19 November 2018
+v2.10, 18 October 2019
include::../common/copyright.txt[]
+include::../common/warning-not-maintained.txt[]
+
+
include::../common/welcome.txt[]
[[installing-lttng]]
== Installation
+include::../common/warning-no-installation.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
trace user applications.
Most distributions mark the LTTng-modules and LTTng-UST packages as
-optional when installing LTTng-tools (which is always required). In the
-following sections, we always provide the steps to install all three,
-but note that:
+optional when installing LTTng-tools (which is always required). Note
+that:
* You only need to install LTTng-modules if you intend to trace the
Linux kernel.
* You only need to install LTTng-UST if you intend to trace user
applications.
-[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 12 November 2018.
-|====
-|Distribution |Available in releases |Alternatives
-
-|https://www.ubuntu.com/[Ubuntu]
-|<<ubuntu,Ubuntu{nbsp}18.04 _Bionic Beaver_>>.
-
-Ubuntu{nbsp}14.04 _Trusty Tahr_, Ubuntu{nbsp}16.04 _Xenial Xerus_,
-and Ubuntu{nbsp}18.04 _Bionic Beaver_:
-<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|https://getfedora.org/[Fedora]
-|xref:fedora[Fedora{nbsp}27, Fedora{nbsp}28, and Fedora{nbsp}29].
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|https://www.debian.org/[Debian]
-|<<debian,Debian "buster" (testing)>>.
-|<<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>>.
-
-|https://alpinelinux.org/[Alpine Linux]
-|<<alpine-linux,Alpine Linux{nbsp}3.7 and Alpine Linux{nbsp}3.8>>.
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|https://www.opensuse.org/[openSUSE]
-|<<opensuse,openSUSE Leap{nbsp}15.0>>.
-|<<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]
-|xref:buildroot[Buildroot{nbsp}2018.02, Buildroot{nbsp}2018.05,
-Buildroot{nbsp}2018.08, and Buildroot{nbsp}2018.11].
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and
-https://www.yoctoproject.org/[Yocto]
-|_Not available_
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-|====
-
-
-[[ubuntu]]
-=== [[ubuntu-official-repositories]]Ubuntu
-
-LTTng{nbsp}{revision} is available on Ubuntu{nbsp}18.04 _Bionic Beaver_.
-For previous supported releases of Ubuntu,
-<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
-
-To install LTTng{nbsp}{revision} on Ubuntu{nbsp}18.04 _Bionic Beaver_:
-
-. 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_
-* Ubuntu{nbsp}18.04 _Bionic Beaver_
-
-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.10
-# 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
-----
---
-
-. **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
-----
---
-
-
-[[fedora]]
-=== Fedora
-
-To install LTTng{nbsp}{revision} on Fedora{nbsp}27, Fedora{nbsp}28,
-or Fedora{nbsp}29:
-
-. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision}
- packages:
-+
---
-[role="term"]
-----
-# yum install lttng-tools
-# yum install lttng-ust
-----
---
-
-. 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.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
-----
---
-
-[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.
-====
-
-
-[[debian]]
-=== Debian
-
-To install LTTng{nbsp}{revision} on Debian "buster" (testing):
-
-. Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-# 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:
-+
---
-[role="term"]
-----
-# 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"]
-----
-# apt-get install python3-lttngust
-----
---
-
-
-[[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].
-
-To install LTTng{nbsp}{revision} on Arch Linux, using
-https://github.com/rmarquis/pacaur[pacaur] for the AUR packages:
-
-. Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-# pacman -Sy lttng-ust
-$ pikaur -Sy lttng-tools
-$ pikaur -Sy lttng-modules
-----
---
-
-. **If you need to instrument and trace <<python-application,Python
- applications>>**, install the LTTng-UST Python agent:
-+
---
-[role="term"]
-----
-# pacman -Sy python-lttngust
-# pacman -Sy python2-lttngust
-----
---
-
-
-[[alpine-linux]]
-=== Alpine Linux
-
-To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
-Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}3.8:
-
-. Add the LTTng packages:
-+
---
-[role="term"]
-----
-# apk add lttng-tools
-# apk add lttng-ust-dev
-----
---
-
-. 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.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
-----
---
-
-
-[[opensuse]]
-=== noch:{openSUSE}
-
-To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}15.0:
-
-* Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-sudo zypper install lttng-tools
-sudo zypper install lttng-modules
-sudo zypper install lttng-ust-devel
-----
---
-
-[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.
-====
-
-
-[[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, or
-Buildroot{nbsp}2018.11:
-
-. Launch the Buildroot configuration tool:
-+
---
-[role="term"]
-----
-$ make menuconfig
-----
---
-
-. 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**.
-
[[building-from-source]]
=== Build from source
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.
[[prebuilt-ust-helpers]]
=== Prebuilt user space tracing helpers
-The LTTng-UST package provides a few helpers in the form or preloadable
+The LTTng-UST package provides a few helpers in the form of preloadable
shared objects which automatically instrument system functions and
calls.
.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