The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.8, 14 March 2017
+v2.8, 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
.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
+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 openSUSE, you need to build and install
+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.
====
.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
+applications>> on Yocto/OpenEmbedded, 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
+applications>> on Yocto/OpenEmbedded, you need to build and install
LTTng-UST{nbsp}{revision} from source and pass the
`--enable-python-agent` option to the `configure` script.
====
discard mode, the tracer only discards the event record that doesn't
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, LTTng keeps no information when it overwrites a
-sub-buffer before consuming it.
+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 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,
+the exact number of lost event records in those lost sub-buffers is not
+saved to the trace. Trace analyses can use the trace's saved discarded
+event record and sub-buffer counts 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.
* **High event throughput**: In general, prefer bigger sub-buffers to
lower the risk of losing event records.
+
-Having bigger sub-buffers also ensures a lower sub-buffer switching
-frequency.
+Having bigger sub-buffers also ensures a lower
+<<channel-switch-timer,sub-buffer switching frequency>>.
+
The number of sub-buffers is only meaningful if you create the channel
in overwrite mode: in this case, if a sub-buffer overwrite happens, the
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
----
--
-. 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}
----
# ...
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>>::