The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.7, 25 October 2016
+v2.7, 24 July 2017
include::../common/copyright.txt[]
+include::../common/warning-not-maintained.txt[]
+
+
include::../common/welcome.txt[]
[[installing-lttng]]
== Installation
+include::../common/warning-installation-outdated.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
|Fedora
|_Not available_
-|LTTng{nbsp}{revision} for Fedora{nbsp}25 and Fedora{nbsp}26 (not
-released yet).
+|LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} for
+Fedora{nbsp}25 and Fedora{nbsp}26 (both are not released yet).
+
+<<building-from-source,Build LTTng-modules{nbsp}{revision} from
+source>>.
<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
other Fedora releases.
|Arch Linux
|_Not available_
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|
+LTTng{nbsp}2.8 on the AUR.
+
+<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
|Alpine Linux
|_Not available_
[[ubuntu]]
=== [[ubuntu-official-repositories]]Ubuntu
-LTTng{nbsp}{revision} is available on Ubuntu 16.04 _Xenial Xerus_. For
-previous releases of Ubuntu, <<ubuntu-ppa,use the LTTng
+LTTng{nbsp}{revision} is available on Ubuntu{nbsp}16.04 _Xenial Xerus_.
+For previous releases of Ubuntu, <<ubuntu-ppa,use the LTTng
Stable{nbsp}{revision} PPA>>.
To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.04 _Xenial Xerus_:
--
. **If you need to instrument and trace
- <<python-application,Python applications>>**, install the
+ <<python-application,Python{nbsp}3 applications>>**, install the
LTTng-UST Python agent:
+
--
--
. **If you need to instrument and trace
- <<python-application,Python applications>>**, install the
+ <<python-application,Python{nbsp}3 applications>>**, install the
LTTng-UST Python agent:
+
--
An **event** is the consequence of the execution of an _instrumentation
point_, like a 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 occurance of an event,
+time. Different actions can be taken upon the occurrence of an event,
like record the event's payload to a buffer.
An **event record** is the representation of an event in a sub-buffer. A
* **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
Once you <<tpp-header,create a tracepoint provider header file>>, you
can use the `tracepoint()` macro in your application's
source code to insert the tracepoints that this header
-<<defining-tracepoints,defined>> defines.
+<<defining-tracepoints,defines>>.
The `tracepoint()` macro takes at least two parameters: the tracepoint
provider name and the tracepoint name. The corresponding tracepoint
`libemon.so`::
User library shared object file.
-The red star indicates that this object file is instrumented
-(contains code which uses the `tracepoint()` macro). The spring
-symbol between the application and a library means the application is
-linked with the library at build time.
+We use the following symbols in the diagrams of table below:
+
+[role="img-100"]
+.Symbols used in the build scenario diagrams.
+image::ust-sit-symbols.png[]
We assume that path:{.} is part of the env:LD_LIBRARY_PATH environment
variable in the following instructions.
To build the instrumented user library:
. In path:{emon.c}, before including path:{tpp.h}, add the
- following line:
+ following lines:
+
--
[source,c]
To build the instrumented user library:
. In path:{emon.c}, before including path:{tpp.h}, add the
- following line:
+ following lines:
+
--
[source,c]
To build the instrumented user library:
. In path:{emon.c}, before including path:{tpp.h}, add the
- following line:
+ following lines:
+
--
[source,c]
To build the instrumented user library:
. In path:{emon.c}, before including path:{tpp.h}, add the
- following line:
+ following lines:
+
--
[source,c]
entry is enough to create a call graph, since an event record always
contains the ID of the CPU that generated it.
+
-You can use a tool like
-https://sourceware.org/binutils/docs/binutils/addr2line.html[cmd:addr2line]
-to convert function addresses back to source file names and
-line numbers.
+You can use a tool like man:addr2line(1) to convert function addresses
+back to source file names and line numbers.
* **path:{liblttng-ust-cyg-profile.so}** is a more robust variant
which also works in use cases where event records might get discarded or
----
--
-. Edit path:{probes/Makefile} and add your new kernel module object
+. Edit path:{probes/KBuild} and add your new kernel module object
next to the existing ones:
+
--
[source,make]
-.path:{probes/Makefile}
+.path:{probes/KBuild}
----
# ...
--
[role="term"]
----
-lttng create --output=/tmp/some-directory my-session
+lttng create my-session --output=/tmp/some-directory
----
--
--
[role="term"]
----
-lttng create --live my-session
+lttng create my-session --live
----
--
+
--
[role="term"]
----
-lttng create --snapshot my-session
+lttng create my-session --snapshot
----
--
+
--
[role="term"]
----
-lttng create --shm-path=/path/to/shm
+lttng create my-session -shm-path=/path/to/shm
----
--
or a Linux kernel KProbe.
+
An event is said to _occur_ at a specific time. Different actions can
-be taken upon the occurance of an event, like record the event's payload
+be taken upon the occurrence of an event, like record the event's payload
to a sub-buffer.
<<channel-overwrite-mode-vs-discard-mode,event loss mode>>::
projects / lttng-docs.git / blobdiff