The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.10, 22 January 2018
+v2.10, 19 November 2018
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 12 November 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.9#doc-ubuntu[LTTng{nbsp}2.9 for Ubuntu{nbsp}17.04 _Zesty Zapus_ and Ubuntu{nbsp}17.10 _Artful Aardvark_].
+|<<ubuntu,Ubuntu{nbsp}18.04 _Bionic Beaver_>>.
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Ubuntu releases.
+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]
-|<<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}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) 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>>.
+|<<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}"edge">>.
+|<<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]
|
|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, 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_
-|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>>.
+|<<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
* 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:
[[fedora]]
=== Fedora
-To install LTTng{nbsp}{revision} on Fedora{nbsp}27:
+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:
[[debian]]
=== Debian
-To install LTTng{nbsp}{revision} on Debian "buster" (testing)
-or Debian "sid" (unstable):
+To install LTTng{nbsp}{revision} on Debian "buster" (testing):
. Install the main LTTng{nbsp}{revision} packages:
+
[role="term"]
----
# pacman -Sy lttng-ust
-$ pacaur -Sy lttng-tools
-$ pacaur -Sy lttng-modules
+$ pikaur -Sy lttng-tools
+$ pikaur -Sy lttng-modules
----
--
=== Alpine Linux
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}.
+Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}3.8:
+
. Add the LTTng packages:
+
--
----
--
-To install LTTng-modules{nbsp}{revision} (Linux kernel tracing support)
-on Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}"edge":
-
-. Add the vanilla Linux kernel:
-+
---
-[role="term"]
-----
-# apk add linux-vanilla linux-vanilla-dev
-----
---
-
-. Reboot with the vanilla Linux kernel.
. Download, build, and install the latest LTTng-modules{nbsp}{revision}:
+
--
--
+[[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
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
. 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__+,
* **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
----
--
+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
function, this is a custom name given to the event rule. With the
JUL, log4j, and Python domains, this is a logger name.
-With a tracepoint, logger, or system call name, the last character
-can be `*` to match anything that remains.
+With a tracepoint, logger, or system call name, you can use the special
+`*` globbing character to match anything (for example, `sched_*`,
+`my_comp*:*msg_*`).
|All.
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
.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"]
----
projects / lttng-docs.git / blobdiff