The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.12, 25 February 2021
+v2.12, 28 November 2023
include::../common/copyright.txt[]
applications.
[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 25{nbsp}February{nbsp}2021.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 3{nbsp}November{nbsp}2023.
|====
|Distribution |Available in releases
|https://www.ubuntu.com/[Ubuntu]
-|<<ubuntu,Ubuntu 20.10 _Groovy Gorilla_>>.
-
-Ubuntu{nbsp}16.04 _Xenial Xerus_, Ubuntu{nbsp}18.04 _Bionic Beaver_,
-and Ubuntu{nbsp}20.04 _Focal Fossa_:
+|Ubuntu{nbsp}16.04 _Xenial Xerus_, Ubuntu{nbsp}18.04 _Bionic Beaver_,
+Ubuntu{nbsp}20.04 _Focal Fossa_, and Ubuntu{nbsp}22.04 _Jammy Jellyfish_:
<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
|https://www.debian.org/[Debian]
-|<<debian,Debian "bullseye" (testing)>>.
-
-|https://getfedora.org/[Fedora]
-|xref:fedora[Fedora{nbsp}33, Fedora{nbsp}34, and Fedora{nbsp}35].
-
-|https://www.archlinux.org/[Arch Linux]
-|<<arch-linux,_Community_ repository and AUR>>.
+|<<debian,Debian{nbsp}11 _bullseye_>>.
|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES]
|See http://packages.efficios.com/[EfficiOS Enterprise Packages].
|https://alpinelinux.org/[Alpine Linux]
-|<<alpine-linux,Alpine Linux{nbsp}3.12 and Alpine Linux{nbsp}3.13>>.
+|xref:alpine-linux[Alpine Linux{nbsp}3.12, Alpine Linux{nbsp}3.13,
+Alpine Linux{nbsp}3.14, and Alpine Linux{nbsp}3.15].
|https://buildroot.org/[Buildroot]
-|xref:buildroot[Buildroot{nbsp}2020.08 and Buildroot{nbsp}2020.11].
+|xref:buildroot[Buildroot{nbsp}2020.08, Buildroot{nbsp}2020.11,
+Builroot{nbsp}2021.02, Buildroot{nbsp}2021.05, Buildroot{nbsp}2021.08,
+and Builroot{nbsp}2021.11].
|https://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and
https://www.yoctoproject.org/[Yocto]
-|<<oe-yocto,Yocto Project{nbsp}3.2 _Gatesgarth_>>
-(`openembedded-core` layer).
+|xref:oe-yocto[Yocto Project{nbsp}3.2 _Gatesgarth_ and Yocto Project{nbsp}3.3 _Hardknott_].
|====
-[[ubuntu]]
-=== [[ubuntu-official-repositories]]Ubuntu
-
-LTTng{nbsp}{revision} is available on Ubuntu{nbsp}20.10 _Groovy
-Gorilla_. For previous supported releases of Ubuntu, <<ubuntu-ppa,use
-the LTTng Stable{nbsp}{revision} PPA>>.
-
-To install LTTng{nbsp}{revision} on Ubuntu{nbsp}20.10 _Groovy Gorilla_:
-
-. 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]]
=== Ubuntu: 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}16.04 _Xenial Xerus_,
-Ubuntu{nbsp}18.04 _Bionic Beaver_, and Ubuntu{nbsp}20.04 _Focal Fossa_.
+Ubuntu{nbsp}18.04 _Bionic Beaver_, Ubuntu{nbsp}20.04 _Focal Fossa_,
+and Ubuntu{nbsp}22.04 _Jammy Jellyfish_.
To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision}
PPA:
[[debian]]
=== Debian
-To install LTTng{nbsp}{revision} on Debian "bullseye" (testing):
+To install LTTng{nbsp}{revision} on Debian{nbsp}11 _bullseye_:
. Install the main LTTng{nbsp}{revision} packages:
+
----
--
-
-[[fedora]]
-=== Fedora
-
-To install LTTng{nbsp}{revision} on Fedora{nbsp}33, Fedora{nbsp}34, or
-Fedora{nbsp}35:
-
-. 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.12.tar.bz2 &&
-tar -xf lttng-modules-latest-2.12.tar.bz2 &&
-cd lttng-modules-2.12.* &&
-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.
-====
-
-
-[[arch-linux]]
-=== Arch Linux
-
-LTTng-UST{nbsp}{revision} is available in the _community_
-repository of Arch Linux, 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/Jguer/yay[yay] for the AUR packages:
-
-. Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-# pacman -Sy lttng-ust
-$ yay -Sy lttng-tools
-$ yay -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.12 or Alpine Linux{nbsp}3.13:
+Alpine Linux{nbsp}3.12, Alpine Linux{nbsp}3.13, Alpine Linux{nbsp}3.14,
+or Alpine Linux{nbsp}3.15:
. Add the LTTng packages:
+
[[buildroot]]
=== Buildroot
-To install LTTng{nbsp}{revision} on Buildroot{nbsp}2020.08 or
-Buildroot{nbsp}2020.11:
+To install LTTng{nbsp}{revision} on Buildroot{nbsp}2020.08, Buildroot{nbsp}2020.11,
+Buildroot{nbsp}2021.02, Buildroot{nbsp}2021.05, Buildroot{nbsp}2021.08, or
+Buildroot{nbsp}2021.11:
. Launch the Buildroot configuration tool:
+
LTTng{nbsp}{revision} recipes are available in the
https://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/[`openembedded-core`]
-layer for Yocto Project{nbsp}3.2 _Gatesgarth_ under the following names:
+layer for Yocto Project{nbsp}3.2 _Gatesgarth_ and Yocto Project{nbsp}3.3 _Hardknott_
+under the following names:
* `lttng-tools`
* `lttng-modules`
LTTng without installing it on your system.
+[[linux-kernel-sig]]
+=== Linux kernel module signature
+
+Linux kernel modules require trusted signatures in order to be loaded
+when any of the following is true:
+
+* The system boots with
+ https://uefi.org/specs/UEFI/2.10/32_Secure_Boot_and_Driver_Signing.html#secure-boot-and-driver-signing[Secure Boot]
+ enabled.
+
+* The Linux kernel which boots is configured with
+ `CONFIG_MODULE_SIG_FORCE`.
+
+* The Linux kernel boots with a command line containing
+ `module.sig_enforce=1`.
+
+.`root` user running <<lttng-sessiond,`lttng-sessiond`>> which fails to load a required <<lttng-modules,kernel module>> due to the signature enforcement policies.
+====
+[role="term"]
+----
+# lttng-sessiond
+Warning: No tracing group detected
+modprobe: ERROR: could not insert 'lttng_ring_buffer_client_discard': Key was rejected by service
+Error: Unable to load required module lttng-ring-buffer-client-discard
+Warning: No kernel tracer available
+----
+====
+
+There are several methods to enroll trusted keys for signing modules
+that are built from source. The precise details vary from one Linux
+version to another, and distributions may have their own mechanisms. For
+example, https://github.com/dell/dkms[DKMS] may autogenerate a key and
+sign modules, but the key isn't automatically enrolled.
+
+See
+https://www.kernel.org/doc/html/latest/admin-guide/module-signing.html[Kernel
+module signing facility] and the documentation of your distribution
+to learn more about signing Linux kernel modules.
+
[[getting-started]]
== Quick start
kernel>> and <<tracing-your-own-user-application,Trace a user
application>> tutorials, you can inspect the recorded events.
-There are many tools you can use to read LTTng traces:
+There are tools you can use to read LTTng traces:
https://babeltrace.org/[Babeltrace{nbsp}2]::
A rich, flexible trace manipulation toolkit which includes
A graphical user interface for viewing and analyzing any type of
logs or traces, including those of LTTng.
-https://github.com/lttng/lttng-analyses[**LTTng analyses**]::
- An experimental project which includes many high-level analyses of
- LTTng kernel traces, like scheduling statistics, interrupt
- frequency distribution, top CPU usage, and more.
-
NOTE: This section assumes that LTTng saved the traces it recorded
during the previous tutorials to their default location, in the
dir:{$LTTNG_HOME/lttng-traces} directory. The env:LTTNG_HOME
_tracing session mode_ dictates where to send it. The following modes
are available in LTTng{nbsp}{revision}:
-Local mode::
+[[local-mode]]Local mode::
LTTng writes the traces to the file system of the machine it traces
(target system).
-Network streaming mode::
+[[net-streaming-mode]]Network streaming mode::
LTTng sends the traces over the network to a
<<lttng-relayd,relay daemon>> running on a remote system.
to write it to the file system of the target or to send it over the
network to a <<lttng-relayd,relay daemon>> running on a remote system.
-Live mode::
+[[live-mode]]Live mode::
This mode is similar to the network streaming mode, but a live
trace viewer can connect to the distant relay daemon to
<<lttng-live,view event records as LTTng generates them>>.
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, since LTTng{nbsp}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, LTTng doesn't write to the trace the exact number of lost event
-records in those lost sub-buffers. Trace analyses can use saved
-discarded event record and sub-buffer counts of the trace to decide
-whether or not to perform the analyses even if trace data is known to be
-missing.
+event record is lost and saves this count to the trace. Since
+LTTng{nbsp}2.8, in overwrite mode, LTTng writes to a given sub-buffer
+its sequence number within its data stream. With a <<local-mode,local>>,
+<<net-streaming-mode,network streaming>>, or <<live-mode,live>>
+<<tracing-session,tracing session>>, a trace reader can use such
+sequence numbers to report lost packets. In overwrite mode, LTTng
+doesn't write to the trace the exact number of lost event records in
+those lost sub-buffers.
+
+Trace analyses can use saved discarded event record and sub-buffer
+(packet) counts of the trace 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.
Generally, you don't have to load the LTTng kernel modules manually
(using man:modprobe(8), for example): a root <<lttng-sessiond,session
daemon>> loads the necessary modules when starting. If you have extra
-probe modules, you can specify to load them to the session daemon on
-the command line.
+probe modules, you can specify to load them to the session daemon on the
+command line. See also
+<<linux-kernel-sig,Linux kernel module signature>>.
The LTTng kernel modules are installed in
+/usr/lib/modules/__release__/extra+ by default, where +__release__+ is
to typical _storage_.
Linux supports NVRAM file systems thanks to either
-http://pramfs.sourceforge.net/[PRAMFS] or
https://www.kernel.org/doc/Documentation/filesystems/dax.txt[DAX]{nbsp}+{nbsp}http://lkml.iu.edu/hypermail/linux/kernel/1504.1/03463.html[pmem]
-(requires Linux{nbsp}4.1+).
+(requires Linux{nbsp}4.1+) or http://pramfs.sourceforge.net/[PRAMFS] (requires Linux{nbsp}<{nbsp}4).
This section doesn't describe how to operate such file systems;
we assume that you have a working persistent memory file system.
project which you can use to send and receive control messages to and
from a <<def-session-daemon,session daemon>>.
-LTTng analyses::
- The https://github.com/lttng/lttng-analyses[LTTng analyses] project,
- which is a set of analyzing programs that you can use to obtain a
- higher level view of an <<def-lttng,LTTng>> <<def-trace,trace>>.
-
cmd:lttng-consumerd::
The name of the <<def-consumer-daemon,consumer daemon>> program.
projects / lttng-docs.git / blobdiff