The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.11, 19 November 2018
+v2.11, 6 April 2020
include::../common/copyright.txt[]
== What's new in LTTng{nbsp}{revision}?
LTTng{nbsp}{revision} bears the name _Lafontaine_. This modern
-https://en.wikipedia.org/wiki/Saison[saison] from the
+https://en.wikipedia.org/wiki/saison[saison] from the
https://oshlag.com/[Oshlag] microbrewery is a refreshing--zesty--rice
beer with hints of fruit and spices. Some even say it makes for a great
https://en.wikipedia.org/wiki/Somaek[Somaek] when mixed with
+
The option also supports tracing existing
https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[SystemTap
-Statically Defined Tracing] (SDT) probe (DTrace-style marker). For example,
-given the following probe:
+Statically Defined Tracing] (USDT) probe (DTrace-style marker). For
+example, given the following probe:
+
[source,c]
----
+
[role="term"]
----
-$ lttng enable-event --kernel --syscall read
+$ lttng enable-event --kernel --syscall open
$ lttng add-context --kernel --type=callstack-kernel --type=callstack-user
----
+
NOTE: LTTng cannot always sample the user space call stack reliably.
For instance, LTTng cannot sample the call stack of user applications
and libraries compiled with the
-https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html[`-fomit-frame pointer`]
+https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html[`-fomit-frame-pointer`]
option. In such a case, the tracing is not affected, but the sampled
user space call stack may only contain the user call stack's topmost
address.
-* The <<lttng-relayd,relay daemon>> is more efficient and presents fewer
- connectivity issues, especially when a large number of targets send
- trace data to a given relay daemon.
-
* User applications and libraries instrumented with
<<lttng-ust,LTTng-UST>> can now safely unload (man:dlclose(3)) a
dynamically loaded
<<building-tracepoint-providers-and-user-application,tracepoint
provider package>>.
+* The <<lttng-relayd,relay daemon>> is more efficient and presents fewer
+ connectivity issues, especially when a large number of targets send
+ trace data to a given relay daemon.
+
+* LTTng-UST uses https://github.com/numactl/numactl[libnuma]
+ when available to allocate <<def-sub-buffer,sub-buffers>>, making them
+ local to each
+ https://en.wikipedia.org/wiki/Non-uniform_memory_access[NUMA] node.
++
+This change makes the tracer more efficient on NUMA systems.
+
+* The <<proc-lttng-logger-abi,LTTng logger>> kernel module now also
+ creates a ``misc'' device named `lttng-logger`, which udev will
+ make accessible as the path:{/dev/lttng-logger} special file.
++
+The `lttng-logger` device shares the `/proc/lttng-logger` file's ABI,
+but it works from within containers when the path is made accessible to
+them.
+
[[nuts-and-bolts]]
== Nuts and bolts
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.
tracing, enable and disable event rules, and the rest). Those
components are bundled into the following packages:
-* **LTTng-tools**: Libraries and command-line interface to
- control tracing.
-* **LTTng-modules**: Linux kernel modules to instrument and
- trace the kernel.
-* **LTTng-UST**: Libraries and Java/Python packages to instrument and
- trace user applications.
+LTTng-tools::
+ Libraries and command-line interface to control tracing.
+
+LTTng-modules::
+ Linux kernel modules to instrument and trace the kernel.
+
+LTTng-UST::
+ Libraries and Java/Python packages to instrument and 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
applications.
[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 12 November 2018.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 30 March 2020.
|====
-|Distribution |Available in releases |Alternatives
+|Distribution |Available in releases
|https://www.ubuntu.com/[Ubuntu]
-|Ubuntu{nbsp}14.04 _Trusty Tahr_, Ubuntu{nbsp}16.04 _Xenial Xerus_,
-and Ubuntu{nbsp}18.04 _Bionic Beaver_:
+|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]
-|_Not available_
-|
-link:/docs/v2.10#doc-fedora[LTTng{nbsp}2.10 for Fedora{nbsp}27,
-Fedora{nbsp}28, and Fedora{nbsp}29].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|https://www.debian.org/[Debian]
-|_Not available_
-|link:/docs/v2.10#doc-debian[LTTng{nbsp}2.10 for Debian "buster" (testing)].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|<<debian,Debian "bullseye" (testing)>>.
|https://www.archlinux.org/[Arch Linux]
-|_Not available_
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|https://alpinelinux.org/[Alpine Linux]
-|_Not available_
-|
-link:/docs/v2.10#doc-alpine-linux[LTTng{nbsp}2.10 for
-Alpine Linux{nbsp}3.7 and Alpine Linux{nbsp}3.8].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|<<arch-linux,_Community_ repository and AUR>>.
-|https://www.opensuse.org/[openSUSE]
-|_Not available_
-|link:/docs/v2.10#doc-opensuse[LTTng{nbsp}2.10 for openSUSE Leap{nbsp}15.0].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|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]
-|_Not available_
-|
-link:/docs/v2.10#doc-buildroot[LTTng{nbsp}2.10 for 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>>.
+|xref:buildroot[Buildroot{nbsp}2019.11 and Buildroot{nbsp}2020.02].
|====
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_
+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:
+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:
--
-[[enterprise-distributions]]
-=== RHEL, SUSE, and other enterprise distributions
+[[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
-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].
+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
+====
+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.
+====
+
+
+[[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]]
. 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
----
--
+
-You need to stop tracing to make LTTng flush the remaining trace data
-and make the trace readable.
-+
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
----
--
+
-You need to stop tracing to make LTTng flush the remaining trace data
-and make the trace readable.
-+
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__+,
kernel>> and <<tracing-your-own-user-application,Trace a user
application>> tutorials, you can inspect the recorded events.
-Many tools are available to read LTTng traces:
+There are many tools you can use to read LTTng traces:
* **cmd:babeltrace** is a command-line utility which converts trace
formats; it supports the format that LTTng produces, CTF, as well as a
basic text output which can be ++grep++ed. The cmd:babeltrace command
is part of the http://diamon.org/babeltrace[Babeltrace] project.
* Babeltrace also includes
- **https://www.python.org/[Python] bindings** so
+ **https://www.python.org/[Python{nbsp}3] bindings** so
that you can easily open and read an LTTng trace with your own script,
benefiting from the power of Python.
* http://tracecompass.org/[**Trace Compass**]
[[viewing-and-analyzing-your-traces-bt-python]]
-==== Use the Babeltrace Python bindings
+==== Use the Babeltrace{nbsp}1 Python bindings
The <<viewing-and-analyzing-your-traces-bt,text output of cmd:babeltrace>>
is useful to isolate events by simple matching using man:grep(1) and
most basic computations involving multiple event records are virtually
impossible to implement.
-Fortunately, Babeltrace ships with Python{nbsp}3 bindings which makes it
-easy to read the event records of an LTTng trace sequentially and
-compute the desired information.
+Fortunately, Babeltrace{nbsp}1 ships with Python{nbsp}3 bindings which
+makes it easy to read the event records of an LTTng trace sequentially
+and compute the desired information.
The following script accepts an LTTng Linux kernel trace path as its
first argument and prints the short names of the top five running
<<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>>.
maximum count, the oldest trace file is overwritten. This mechanism is
called _trace file rotation_.
+[IMPORTANT]
+====
Even if you don't limit the trace file count, you cannot assume that
-LTTng doesn't manage any trace file. In other words, there is no safe
-way to know if LTTng still holds a given trace file open with the trace
-file rotation feature. The only way to obtain an unmanaged,
-self-contained LTTng trace before you
-<<creating-destroying-tracing-sessions,destroy>> the tracing session is
-with the <<session-rotation,tracing session rotation>> feature
+LTTng doesn't manage any trace file.
+
+In other words, there is no safe way to know if LTTng still holds a
+given trace file open with the trace file rotation feature.
+
+The only way to obtain an unmanaged, self-contained LTTng trace before
+you <<creating-destroying-tracing-sessions,destroy>> the tracing session
+is with the <<session-rotation,tracing session rotation>> feature
(available since LTTng{nbsp}2.11).
+====
[[event]]
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]]
* The _LTTng logger_ module.
+
The LTTng logger module implements the special path:{/proc/lttng-logger}
-file so that any executable can generate LTTng events by opening and
-writing to this file.
+(and path:{/dev/lttng-logger} since LTTng{nbsp}2.11) files so that any
+executable can generate LTTng events by opening and writing to those
+files.
+
See <<proc-lttng-logger-abi,LTTng logger>>.
.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
=== LTTng logger
The `lttng-tracer` Linux kernel module, part of
-<<lttng-modules,LTTng-modules>>, creates the special LTTng logger file
-path:{/proc/lttng-logger} when it's loaded. Any application can write
-text data to this file to emit an LTTng event.
+<<lttng-modules,LTTng-modules>>, creates the special LTTng logger files
+path:{/proc/lttng-logger} and path:{/dev/lttng-logger} (since
+LTTng{nbsp}2.11) when it's loaded. Any application can write text data
+to any of those files to emit an LTTng event.
[role="img-100"]
.An application writes to the LTTng logger file to emit an LTTng event.
[role="term"]
----
-$ echo "Some message, some $variable" > /proc/lttng-logger
+$ echo "Some message, some $variable" > /dev/lttng-logger
----
Any event that the LTTng logger emits is named `lttng_logger` and
To use the LTTng logger:
-* From any application, write text data to the path:{/proc/lttng-logger}
+* From any application, write text data to the path:{/dev/lttng-logger}
file.
The `msg` field of `lttng_logger` event records contains the
[source,bash]
.path:{test.bash}
----
-echo 'Hello, World!' > /proc/lttng-logger
+echo 'Hello, World!' > /dev/lttng-logger
sleep 2
-df --human-readable --print-type / > /proc/lttng-logger
+df --human-readable --print-type / > /dev/lttng-logger
----
<<creating-destroying-tracing-sessions,Create a 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.
+
[[list-instrumentation-points]]
=== List the available instrumentation points
. The entry point of a user application or library function (path to
application/library and symbol).
. A https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[SystemTap
- Statically Defined Tracing] (SDT) probe (path to application/library,
+ Statically Defined Tracing] (USDT) probe (path to application/library,
provider and probe names).
|Linux kernel.
----
====
-.Create an event rule matching the `server`/`accept_request` https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[SDT probe] in path:{/usr/bin/serv}:
+.Create an event rule matching the `server`/`accept_request` https://www.sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps[USDT probe] in path:{/usr/bin/serv}:
====
[role="term"]
----
man:lttng-stop(1) command.
IMPORTANT: You need to stop tracing to make LTTng flush the remaining
-trace data and make the trace readable.
+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]]
**process priority** of the thread in which the event occurs.
* The **hostname** of the system on which the event occurs.
* The Linux kernel and user call stacks (since
- LTTng{nbsp}{revision}).
+ LTTng{nbsp}11).
* The current values of many possible **performance counters** using
perf, for example:
** CPU cycles, stalled cycles, idle cycles, and the other cycle types.
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.
What LTTng is about to write when performing a tracing session rotation
is called the _current trace chunk_. When this current trace chunk is
-written to the file system or sent over the network, it is called a
-_trace chunk archive_. Therefore, a tracing session rotation _archives_
-the current trace chunk.
+written to the file system or sent over the network, it becomes a _trace
+chunk archive_. Therefore, a tracing session rotation _archives_ the
+current trace chunk.
[role="img-100"]
.A tracing session rotation operation _archives_ the current trace chunk.
image::rotation.png[]
-A trace chunk archive is a self-contained LTTng trace and is not managed
-anymore by LTTng: you can read it, modify it, move it, or remove it.
+A trace chunk archive is a self-contained LTTng trace which LTTng
+doesn't manage anymore: you can read it, modify it, move it, or remove
+it.
-There are two methods to perform a tracing session rotation:
-immediately or automatically.
+There are two methods to perform a tracing session rotation: immediately
+or with a rotation schedule.
To perform an immediate tracing session rotation:
--
. <<enabling-disabling-events,Create one or more event rules>>
-and <<basic-tracing-session-control,start tracing>>:
+ and <<basic-tracing-session-control,start tracing>>:
+
--
[role="term"]
You can perform other immediate rotations while the tracing session is
active. It is guaranteed that all the trace chunk archives do not
contain overlapping trace data. You can also perform an immediate
-rotation once the tracing session is
-<<basic-tracing-session-control,stopped>>.
+rotation once you have <<basic-tracing-session-control,stopped>> the
+tracing session.
. When you are done tracing,
<<creating-destroying-tracing-sessions,destroy the current tracing
The tracing session destruction operation creates one last trace
chunk archive from the current trace chunk.
-An automatic tracing session rotation is a rotation which LTTng
+A tracing session rotation schedule is a planned rotation which LTTng
performs automatically based on one of the following conditions:
* A timer with a configured period times out.
+
* The total size of the flushed part of the current trace chunk
becomes greater than or equal to a configured value.
-To configure a future, automatic tracing session rotation, you need
-to set a _rotation schedule_.
-
-To set a rotation schedule:
+To schedule a tracing session rotation, set a _rotation schedule_:
. <<creating-destroying-tracing-sessions,Create a tracing session>>
in _normal mode_ or _network streaming mode_
--
[role="term"]
----
-$ lttng enable-rotation --timer=12s
+$ lttng enable-rotation --timer=10s
----
--
+
In this example, we set a rotation schedule so that LTTng performs a
-tracing session rotation every 12{nbsp}seconds.
+tracing session rotation every ten seconds.
+
See man:lttng-enable-rotation(1) to learn more about other ways to set a
rotation schedule.
The tracing session destruction operation creates one last trace chunk
archive from the current trace chunk.
-You can use man:lttng-disable-rotation(1) to unset an a tracing session
+You can use man:lttng-disable-rotation(1) to unset a tracing session
rotation schedule.
NOTE: man:lttng-rotate(1) and man:lttng-enable-rotation(1) list
Terms related to LTTng and to tracing in general:
Babeltrace::
- The http://diamon.org/babeltrace[Babeltrace] project, which includes
- the cmd:babeltrace command, libraries, and Python bindings.
+ The http://diamon.org/babeltrace[Babeltrace] project, which includes:
++
+* The cmd:babeltrace (Babeltrace{nbsp}1) or cmd:babeltrace2
+ (Babeltrace{nbsp}2) command.
+* Libraries with a C{nbsp}API.
+* Python{nbsp}3 bindings.
+* Plugins (Babeltrace{nbsp}2).
[[def-buffering-scheme]]<<channel-buffering-schemes,buffering scheme>>::
A layout of <<def-sub-buffer,sub-buffers>> applied to a given channel.
-<<channel,channel>>::
+[[def-channel]]<<channel,channel>>::
An entity which is responsible for a set of
<<def-ring-buffer,ring buffers>>.
+
-<<event,Event rules>> are always attached to a specific channel.
+<<def-event-rule,Event rules>> are always attached to a specific
+channel.
clock::
A source of time for a <<def-tracer,tracer>>.
-<<lttng-consumerd,consumer daemon>>::
+[[def-consumer-daemon]]<<lttng-consumerd,consumer daemon>>::
A process which is responsible for consuming the full
<<def-sub-buffer,sub-buffers>> and write them to a file system or
send them over the network.
[[def-current-trace-chunk]]current trace chunk::
A <<def-trace-chunk,trace chunk>> which includes the current content
- of all the <<tracing-session,tracing session>>'s
+ of all the <<def-tracing-session-rotation,tracing session>>'s
<<def-sub-buffer,sub-buffers>> and the stream files produced since the
latest event amongst:
+
-* The creation of the tracing session.
-* The last <<session-rotation,tracing session rotation>>, if any.
+* The creation of the <<def-tracing-session,tracing session>>.
+* The last tracing session rotation, if any.
-<<channel-overwrite-mode-vs-discard-mode,discard mode>>:: The event
- record loss mode in which the <<def-tracer,tracer>> _discards_ new
- event records when there's no
+<<channel-overwrite-mode-vs-discard-mode,discard mode>>::
+ The <<def-event-record-loss-mode,event record loss mode>> in which
+ the <<def-tracer,tracer>> _discards_ new event records when there's no
<<def-sub-buffer,sub-buffer>> space left to store them.
[[def-event]]event::
<<def-tracepoint,tracepoint>> that you manually place in some source
code, or a Linux kernel kprobe.
+
-An event is said to _occur_ at a specific time. Different actions can
-be taken upon the occurrence of an event, like record the event's payload
-to a <<def-sub-buffer,sub-buffer>>.
+An event is said to _occur_ at a specific time. <<def-lttng,LTTng>> can
+take various actions upon the occurrence of an event, like record the
+event's payload to a <<def-sub-buffer,sub-buffer>>.
[[def-event-name]]event name::
- The name of an event, which is also the name of the event record.
- This is also called the _instrumentation point name_.
+ The name of an <<def-event,event>>, which is also the name of the
+ <<def-event-record,event record>>.
++
+This is also called the _instrumentation point name_.
[[def-event-record]]event record::
- A record, in a <<def-trace,trace>>, of the payload of an event
- which occured.
+ A record, in a <<def-trace,trace>>, of the payload of an
+ <<def-event,event>> which occured.
[[def-event-record-loss-mode]]<<channel-overwrite-mode-vs-discard-mode,event record loss mode>>::
- The mechanism by which event records of a given <<channel,channel>>
- are lost (not recorded) when there is no <<def-sub-buffer,sub-buffer>>
- space left to store them.
+ The mechanism by which event records of a given
+ <<def-channel,channel>> are lost (not recorded) when there is no
+ <<def-sub-buffer,sub-buffer>> space left to store them.
-<<event,event rule>>::
+[[def-event-rule]]<<event,event rule>>::
Set of conditions which must be satisfied for one or more occuring
- events to be recorded.
+ <<def-event,events>> to be recorded.
`java.util.logging`::
Java platform's
https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html[core logging facilities].
<<instrumenting,instrumentation>>::
- The use of LTTng probes to make a piece of software traceable.
+ The use of <<def-lttng,LTTng>> probes to make a piece of software
+ traceable.
[[def-instrumentation-point]]instrumentation point::
A point in the execution path of a piece of software that, when
log level::
Level of severity of a log statement or user space
- instrumentation point.
+ <<def-instrumentation-point,instrumentation point>>.
-LTTng::
+[[def-lttng]]LTTng::
The _Linux Trace Toolkit: next generation_ project.
<<lttng-cli,cmd:lttng>>::
- A command-line tool provided by the LTTng-tools project which you
- can use to send and receive control messages to and from a
- session daemon.
+ A command-line tool provided by the <<def-lttng-tools,LTTng-tools>>
+ 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 are used to obtain a
- higher level view of an LTTng <<def-trace,trace>>.
+ 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 consumer daemon program.
+ The name of the <<def-consumer-daemon,consumer daemon>> program.
cmd:lttng-crash::
- A utility provided by the LTTng-tools project which can convert
- <<def-ring-buffer,ring buffer>> files (usually
- <<persistent-memory-file-systems,saved on a persistent memory file system>>)
- to <<def-trace,trace>> files.
+ A utility provided by the <<def-lttng-tools,LTTng-tools>> project
+ which can convert <<def-ring-buffer,ring buffer>> files (usually
+ <<persistent-memory-file-systems,saved on a persistent memory file
+ system>>) to <<def-trace,trace>> files.
++
+See man:lttng-crash(1).
LTTng Documentation::
This document.
<<lttng-live,LTTng live>>::
A communication protocol between the <<lttng-relayd,relay daemon>> and
live viewers which makes it possible to see <<def-event-record,event
- records>> "live", as they are received by the relay daemon.
+ records>> "live", as they are received by the
+ <<def-relay-daemon,relay daemon>>.
<<lttng-modules,LTTng-modules>>::
The https://github.com/lttng/lttng-modules[LTTng-modules] project,
which contains the Linux kernel modules to make the Linux kernel
<<def-instrumentation-point,instrumentation points>> available for
- LTTng tracing.
+ <<def-lttng,LTTng>> tracing.
cmd:lttng-relayd::
- The name of the <<lttng-relayd,relay daemon>> program.
+ The name of the <<def-relay-daemon,relay daemon>> program.
cmd:lttng-sessiond::
- The name of the <<lttng-sessiond,session daemon>> program.
+ The name of the <<def-session-daemon,session daemon>> program.
-LTTng-tools::
+[[def-lttng-tools]]LTTng-tools::
The https://github.com/lttng/lttng-tools[LTTng-tools] project, which
contains the various programs and libraries used to
<<controlling-tracing,control tracing>>.
-<<lttng-ust,LTTng-UST>>::
+[[def-lttng-ust]]<<lttng-ust,LTTng-UST>>::
The https://github.com/lttng/lttng-ust[LTTng-UST] project, which
contains libraries to instrument
<<def-user-application,user applications>>.
<<lttng-ust-agents,LTTng-UST Java agent>>::
- A Java package provided by the LTTng-UST project to allow the
- LTTng instrumentation of `java.util.logging` and Apache log4j{nbsp}1.2
- logging statements.
+ A Java package provided by the <<def-lttng-ust,LTTng-UST>> project to
+ allow the LTTng instrumentation of `java.util.logging` and Apache
+ log4j{nbsp}1.2 logging statements.
<<lttng-ust-agents,LTTng-UST Python agent>>::
- A Python package provided by the LTTng-UST project to allow the
- LTTng instrumentation of Python logging statements.
+ A Python package provided by the <<def-lttng-ust,LTTng-UST>> project
+ to allow the <<def-lttng,LTTng>> instrumentation of Python logging
+ statements.
<<channel-overwrite-mode-vs-discard-mode,overwrite mode>>::
The <<def-event-record-loss-mode,event record loss mode>> in which new
<<channel-buffering-schemes,per-process buffering>>::
A <<def-buffering-scheme,buffering scheme>> in which each instrumented
process has its own <<def-sub-buffer,sub-buffers>> for a given user
- space <<channel,channel>>.
+ space <<def-channel,channel>>.
<<channel-buffering-schemes,per-user buffering>>::
A <<def-buffering-scheme,buffering scheme>> in which all the processes
of a Unix user share the same <<def-sub-buffer,sub-buffers>> for a
- given user space <<channel,channel>>.
+ given user space <<def-channel,channel>>.
-<<lttng-relayd,relay daemon>>::
+[[def-relay-daemon]]<<lttng-relayd,relay daemon>>::
A process which is responsible for receiving the <<def-trace,trace>>
- data sent by a distant <<lttng-consumerd,consumer daemon>>.
+ data which a distant <<def-consumer-daemon,consumer daemon>> sends.
[[def-ring-buffer]]ring buffer::
A set of <<def-sub-buffer,sub-buffers>>.
rotation::
See _<<def-tracing-session-rotation,tracing session rotation>>_.
-<<lttng-sessiond,session daemon>>::
+[[def-session-daemon]]<<lttng-sessiond,session daemon>>::
A process which receives control commands from you and orchestrates
- the <<def-tracer,tracers>> and various LTTng daemons.
+ the <<def-tracer,tracers>> and various <<def-lttng,LTTng>> daemons.
<<taking-a-snapshot,snapshot>>::
A copy of the current data of all the <<def-sub-buffer,sub-buffers>>
- of a given <<tracing-session,tracing session>>, saved as
+ of a given <<def-tracing-session,tracing session>>, saved as
<<def-trace,trace>> files.
[[def-sub-buffer]]sub-buffer::
- One part of an LTTng <<def-ring-buffer,ring buffer>> which contains
- <<def-event-record,event records>>.
+ One part of an <<def-lttng,LTTng>> <<def-ring-buffer,ring buffer>>
+ which contains <<def-event-record,event records>>.
timestamp::
- The time information attached to an
- <<def-event,event>> when it is emitted.
+ The time information attached to an <<def-event,event>> when it is
+ emitted.
[[def-trace]]trace (_noun_)::
A set of:
* One or more CTF data stream files which are the concatenations of one
or more flushed <<def-sub-buffer,sub-buffers>>.
-trace (_verb_)::
+[[def-trace-verb]]trace (_verb_)::
The action of recording the <<def-event,events>> emitted by an
application or by a system, or to initiate such recording by
- controlling a tracer.
+ controlling a <<def-tracer,tracer>>.
[[def-trace-chunk]]trace chunk::
- A self-contained trace which is part of a <<tracing-session,tracing
- session>>. Each <<session-rotation, tracing session rotation>>
- produces a trace chunk archive.
+ A self-contained <<def-trace,trace>> which is part of a
+ <<def-tracing-session,tracing session>>. Each
+ <<def-tracing-session-rotation, tracing session rotation>> produces a
+ <<def-trace-chunk-archive,trace chunk archive>>.
-trace chunk archive::
- The result of a <<session-rotation, tracing session rotation>>. A
- trace chunk archive is not managed by LTTng, even if its containing
- <<tracing-session,tracing session>> is still active: you are free to
- read it, modify it, move it, or remove it.
+[[def-trace-chunk-archive]]trace chunk archive::
+ The result of a <<def-tracing-session-rotation, tracing session rotation>>.
++
+<<def-lttng,LTTng>> does not manage any trace chunk archive, even if its
+containing <<def-tracing-session,tracing session>> is still active: you
+are free to read it, modify it, move it, or remove it.
Trace Compass::
The http://tracecompass.org[Trace Compass] project and application.
[[def-tracepoint]]tracepoint::
An instrumentation point using the tracepoint mechanism of the Linux
- kernel or of LTTng-UST.
+ kernel or of <<def-lttng-ust,LTTng-UST>>.
tracepoint definition::
- The definition of a single tracepoint.
+ The definition of a single <<def-tracepoint,tracepoint>>.
tracepoint name::
- The name of a tracepoint.
+ The name of a <<def-tracepoint,tracepoint>>.
-tracepoint provider::
- A set of functions providing tracepoints to an instrumented user
- application.
+[[def-tracepoint-provider]]tracepoint provider::
+ A set of functions providing <<def-tracepoint,tracepoints>> to an
+ instrumented <<def-user-application,user application>>.
+
-Not to be confused with a _tracepoint provider package_: many tracepoint
-providers can exist within a tracepoint provider package.
+Not to be confused with a <<def-tracepoint-provider-package,tracepoint
+provider package>>: many tracepoint providers can exist within a
+tracepoint provider package.
-tracepoint provider package::
- One or more tracepoint providers compiled as an
- https://en.wikipedia.org/wiki/Object_file[object file] or as
- a link:https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries[shared library].
+[[def-tracepoint-provider-package]]tracepoint provider package::
+ One or more <<def-tracepoint-provider,tracepoint providers>> compiled
+ as an https://en.wikipedia.org/wiki/Object_file[object file] or as a
+ link:https://en.wikipedia.org/wiki/Library_(computing)#Shared_libraries[shared
+ library].
[[def-tracer]]tracer::
A software which records emitted <<def-event,events>>.
A namespace for <<def-event,event>> sources.
<<tracing-group,tracing group>>::
- The Unix group in which a Unix user can be to be allowed to trace the
- Linux kernel.
+ The Unix group in which a Unix user can be to be allowed to
+ <<def-trace-verb,trace>> the Linux kernel.
-[[def-tracing-session-rotation]]<<tracing-session,tracing session>>::
- A stateful dialogue between you and a <<lttng-sessiond,session
- daemon>>.
+[[def-tracing-session]]<<tracing-session,tracing session>>::
+ A stateful dialogue between you and a <<lttng-sessiond,session daemon>>.
-<<session-rotation,tracing session rotation>>::
+[[def-tracing-session-rotation]]<<session-rotation,tracing session rotation>>::
The action of archiving the
<<def-current-trace-chunk,current trace chunk>> of a
- <<tracing-session,tracing session>>.
+ <<def-tracing-session,tracing session>>.
[[def-user-application]]user application::
An application running in user space, as opposed to a Linux kernel
projects / lttng-docs.git / blobdiff