The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.11, 18 October 2019
+v2.11, 30 March 2020
include::../common/copyright.txt[]
+
[role="term"]
----
-$ lttng enable-event --kernel --syscall read
+$ lttng enable-event --kernel --syscall open
$ lttng add-context --kernel --type=callstack-kernel --type=callstack-user
----
+
is the de facto function tracer of the Linux kernel. Its user
interface is a set of special files in sysfs.
* https://perf.wiki.kernel.org/[perf] is
- a performance analyzing tool for Linux which supports hardware
+ a performance analysis tool for Linux which supports hardware
performance counters, tracepoints, as well as other counters and
types of probes. perf's controlling utility is the cmd:perf command
line/curses tool.
* 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 30 March 2020.
+|====
+|Distribution |Available in releases
+
+|https://www.ubuntu.com/[Ubuntu]
+|Ubuntu{nbsp}16.04 _Xenial Xerus_ and Ubuntu{nbsp}18.04 _Bionic Beaver_:
+<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
+
+|https://www.debian.org/[Debian]
+|<<debian,Debian "bullseye" (testing)>>.
+
+|https://www.archlinux.org/[Arch Linux]
+|<<arch-linux,_Community_ repository and AUR>>.
+
+|https://getfedora.org/[Fedora]
+|xref:fedora[Fedora{nbsp}32 and Fedora{nbsp}33].
+
+|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}2019.11 and Buildroot{nbsp}2020.02].
+|====
+
+
+[[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_ and
+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
+----
+--
+
+
+[[debian]]
+=== Debian
+
+To install LTTng{nbsp}{revision} on Debian "bullseye" (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/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
+----
+--
+
+
+[[fedora]]
+=== Fedora
+
+To install LTTng{nbsp}{revision} on Fedora{nbsp}32 and Fedora{nbsp}33:
+
+. 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.11.tar.bz2 &&
+tar -xf lttng-modules-latest-2.11.tar.bz2 &&
+cd lttng-modules-2.11.* &&
+make &&
+sudo make modules_install &&
+sudo depmod -a
+----
+--
+
[IMPORTANT]
+.Java and Python application instrumentation and tracing
====
-As of 18 October 2019, LTTng{nbsp}{revision} is not available
-as distribution packages.
+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.
-You can <<building-from-source,build LTTng{nbsp}{revision} from source>>
-to install and use it.
+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.
====
+[[buildroot]]
+=== Buildroot
+
+To install LTTng{nbsp}{revision} on Buildroot{nbsp}2019.11 and
+Buildroot{nbsp}2020.02:
+
+. 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
<<enabling-disabling-events,creating an event rule>> because all the
tracing domains could have tracepoints with the same names.
-Some features are reserved to specific tracing domains. Dynamic function
-entry and return instrumentation points, for example, are currently only
-supported in the Linux kernel tracing domain, but support for other
-tracing domains could be added in the future.
-
You can create <<channel,channels>> in the Linux kernel and user space
tracing domains. The other tracing domains have a single default
channel.
The available event record loss modes are:
Discard mode::
- Drop the newest event records until a the tracer releases a
- sub-buffer.
+ Drop the newest event records until the tracer releases a sub-buffer.
+
This is the only available mode when you specify a
<<opt-blocking-timeout,blocking timeout>>.
You set the conditions when you <<enabling-disabling-events,create
an event rule>>.
-You always attach an event rule to <<channel,channel>> when you create
+You always attach an event rule to a <<channel,channel>> when you create
it.
When an event passes the conditions of an event rule, LTTng records it
sessions, but most of them require to create a handle first using
`lttng_create_handle()`.
-The best available developer documentation for `liblttng-ctl` is, as of
-LTTng{nbsp}{revision}, its installed header files. Every function and
-structure is thoroughly documented.
+As of LTTng{nbsp}{revision}, the best available developer documentation for
+`liblttng-ctl` is its installed header files. Every function and structure is
+thoroughly documented.
[[lttng-ust]]
When LTTng loads a configuration, it restores your saved tracing session
as if you just configured it manually.
-See man:lttng(1) for the complete list of command-line options. You
-can also save and load all many sessions at a time, and decide in which
+See man:lttng-load(1) for the complete list of command-line options. You
+can also save and load many sessions at a time, and decide in which
directory to output the XML files.
projects / lttng-docs.git / blobdiff