Buildroot: installing-lttng: remove superfluous double quotes

[lttng-docs.git] / 2.10 / lttng-docs-2.10.txt

diff --git a/2.10/lttng-docs-2.10.txt b/2.10/lttng-docs-2.10.txt
index e0cfa655437173a164a31a56f03d82db3f56d55f..723be3474a78a5655a58b62428cf1a7655848c7f 100644 (file)
--- a/2.10/lttng-docs-2.10.txt
+++ b/2.10/lttng-docs-2.10.txt
@@ -1,7 +1,7 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>

-v2.10, 1 August 2017
+v2.10, 12 November 2018

 
 
 include::../common/copyright.txt[]
 
 
 include::../common/copyright.txt[]


@@ -138,7 +138,7 @@ instrumented with LTTng-UST which is explicitly allowed to block:
 [role="term"]
 ----
 $ lttng create
 [role="term"]
 ----
 $ lttng create

-$ lttng enable-channel --userspace --blocking-timeout=-1 blocking-channel
+$ lttng enable-channel --userspace --blocking-timeout=inf blocking-channel

 $ lttng enable-event --userspace --channel=blocking-channel --all
 $ lttng start
 $ LTTNG_UST_ALLOW_BLOCKING=1 my-app
 $ lttng enable-event --userspace --channel=blocking-channel --all
 $ lttng start
 $ LTTNG_UST_ALLOW_BLOCKING=1 my-app


@@ -321,65 +321,97 @@ but note that:
   applications.
 
 [role="growable"]
   applications.
 
 [role="growable"]

-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 25 July 2017.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 12 November 2018.

 |====
 |Distribution |Available in releases |Alternatives
 
 |https://www.ubuntu.com/[Ubuntu]
 |====
 |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_].
+|<<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]
 
 |https://getfedora.org/[Fedora]

-|_Not available_
-|link:/docs/v2.9#doc-fedora[LTTng{nbsp}2.9 for Fedora 26].
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
+|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]
 
 |https://www.debian.org/[Debian]

-|_Not available_
-|link:/docs/v2.9#doc-debian[LTTng{nbsp}2.9 for Debian "stretch"
-(stable), Debian "buster" (testing), and Debian "sid" (unstable)].
-
-<<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]
 
 |https://www.archlinux.org/[Arch Linux]

-|_Not available_
-|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 in the latest AUR packages].
+|<<arch-linux,Current Arch Linux build>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.

 
 |https://alpinelinux.org/[Alpine Linux]
 
 |https://alpinelinux.org/[Alpine Linux]

-|_Not available_
-|link:/docs/v2.9#doc-alpine-linux[LTTng{nbsp}2.9 for Alpine Linux "edge"].
+|<<alpine-linux,Alpine Linux{nbsp}3.7 and Alpine Linux{nbsp}3.8>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.

 
 

-<<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]
 |See http://packages.efficios.com/[EfficiOS Enterprise Packages].
 |
 
 |https://buildroot.org/[Buildroot]
 
 |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.9#doc-buildroot[LTTng{nbsp}2.9 for Buildroot{nbsp}2017.02 and
-Buildroot{nbsp}2017.05].
-
-<<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_
 
 |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_]
-(`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
 
 |====
 
 
 [[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-ppa]]
 ==== noch:{LTTng} Stable {revision} PPA
 


@@ -389,6 +421,7 @@ LTTng{nbsp}{revision} packages for:
 
 * Ubuntu{nbsp}14.04 _Trusty Tahr_
 * Ubuntu{nbsp}16.04 _Xenial Xerus_
 
 * 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:
 
 
 To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA:
 


@@ -437,6 +470,191 @@ To install LTTng{nbsp}{revision} from the LTTng Stable{nbsp}{revision} PPA:
 --
 
 
 --
 
 

+[[fedora]]
+=== Fedora
+
+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:
++
+--
+[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.10.tar.bz2 &&
+tar -xf lttng-modules-latest-2.10.tar.bz2 &&
+cd lttng-modules-2.10.* &&
+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.
+====
+
+
+[[debian]]
+=== Debian
+
+To install LTTng{nbsp}{revision} on Debian "buster" (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/rmarquis/pacaur[pacaur] for the AUR packages:
+
+. Install the main LTTng{nbsp}{revision} packages:
++
+--
+[role="term"]
+----
+# pacman -Sy lttng-ust
+$ pikaur -Sy lttng-tools
+$ pikaur -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
+----
+--
+
+
+[[alpine-linux]]
+=== Alpine Linux
+
+To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
+Alpine Linux{nbsp}3.7 or Alpine Linux{nbsp}3.8:
+
+. Add the LTTng packages:
++
+--
+[role="term"]
+----
+# apk add lttng-tools
+# apk add lttng-ust-dev
+----
+--
+
+. 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.10.tar.bz2 &&
+tar -xf lttng-modules-latest-2.10.tar.bz2 &&
+cd lttng-modules-2.10.* &&
+make &&
+sudo make modules_install &&
+sudo depmod -a
+----
+--
+
+
+[[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
 
 [[enterprise-distributions]]
 === RHEL, SUSE, and other enterprise distributions
 


@@ -445,6 +663,30 @@ Enterprise Linux (RHEL) and SUSE Linux Enterprise Server (SUSE), please
 see http://packages.efficios.com/[EfficiOS Enterprise Packages].
 
 
 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}&#8594; **Debugging, profiling and benchmark**,
+  check **lttng-modules** and **lttng-tools**.
+. In **Target packages**{nbsp}&#8594; **Libraries**{nbsp}&#8594;
+  **Other**, check **lttng-libust**.
+
+

 [[building-from-source]]
 === Build from source
 
 [[building-from-source]]
 === Build from source
 


@@ -1290,8 +1532,11 @@ reached, the channel's _event loss mode_ determines what to do. The
 available event loss modes are:
 
 Discard mode::
 available event loss modes are:
 
 Discard mode::

-  Drop the newest event records until a the tracer
-  releases a sub-buffer.
+  Drop the newest event records until a the tracer releases a
+  sub-buffer.
++
+This is the only available mode when you specify a
+<<opt-blocking-timeout,blocking timeout>>.

 
 Overwrite mode::
   Clear the sub-buffer containing the oldest event records and start
 
 Overwrite mode::
   Clear the sub-buffer containing the oldest event records and start


@@ -1305,15 +1550,19 @@ always keep a fixed amount of the latest data.
 Which mechanism you should choose depends on your context: prioritize
 the newest or the oldest event records in the ring buffer?
 
 Which mechanism you should choose depends on your context: prioritize
 the newest or the oldest event records in the ring buffer?
 

-Beware that, in overwrite mode, the tracer abandons a whole sub-buffer
+Beware that, in overwrite mode, the tracer abandons a _whole sub-buffer_

 as soon as a there's no space left for a new event record, whereas in
 discard mode, the tracer only discards the event record that doesn't
 fit.
 
 as soon as a there's no space left for a new event record, whereas in
 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.
 
 There are a few ways to decrease your probability of losing event
 records.


@@ -1528,7 +1777,7 @@ The LTTng project incorporates:
 * **LTTng-tools**: Libraries and command-line interface to
   control tracing sessions.
 ** <<lttng-sessiond,Session daemon>> (man:lttng-sessiond(8)).
 * **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)).
 ** <<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)).


@@ -1824,7 +2073,7 @@ running. You can also start the session daemon manually.
 .The consumer daemon.
 image::plumbing-consumerd.png[]
 
 .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
 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


@@ -5598,8 +5847,9 @@ Tracepoint or system call name. In the case of a Linux KProbe or
 function, this is a custom name given to the event rule. With the
 JUL, log4j, and Python domains, this is a logger name.
 
 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.
 
 
 |All.
 


@@ -5950,7 +6200,7 @@ in blocking mode to +__TIMEOUTUS__+:
 0 (default)::
     Never block (non-blocking mode).
 
 0 (default)::
     Never block (non-blocking mode).
 

--1::
+`inf`::

     Block forever until space is available in a sub-buffer to record
     the event.
 
     Block forever until space is available in a sub-buffer to record
     the event.
 


@@ -6019,7 +6269,7 @@ and <<basic-tracing-session-control,start tracing>>:
 [role="term"]
 ----
 $ lttng create
 [role="term"]
 ----
 $ lttng create

-$ lttng enable-channel --userspace --blocking-timeout=-1 blocking-channel
+$ lttng enable-channel --userspace --blocking-timeout=inf blocking-channel

 $ lttng enable-event --userspace --channel=blocking-channel --all
 $ lttng start
 ----
 $ lttng enable-event --userspace --channel=blocking-channel --all
 $ lttng start
 ----


@@ -6243,8 +6493,8 @@ leads to this whitelist:
 .PIDs 3, 7, 10, and 13 are removed from the whitelist.
 image::track-1-4-15-16.png[]
 
 .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"]
 ----
 
 [role="term"]
 ----