Merge "2.13: Cleanup duplicate paragraph"

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

diff --git a/2.7/lttng-docs-2.7.txt b/2.7/lttng-docs-2.7.txt
index 3210b83645f2306122f46608db8293e2d1324058..6d783239a5d4740f257dd5cd28afb447395b7789 100644 (file)
--- a/2.7/lttng-docs-2.7.txt
+++ b/2.7/lttng-docs-2.7.txt
@@ -1,12 +1,15 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>

-v2.7, 25 October 2016
+v2.7, 24 July 2017

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

+include::../common/warning-not-maintained.txt[]
+
+

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


@@ -286,6 +289,8 @@ becomes inactive or in real-time.
 [[installing-lttng]]
 == Installation
 
 [[installing-lttng]]
 == Installation
 

+include::../common/warning-no-installation.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
 **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


@@ -300,292 +305,14 @@ components are bundled into the following packages:
   trace user applications.
 
 Most distributions mark the LTTng-modules and LTTng-UST packages as
   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
-following sections, we always provide the steps to install all three,
-but note that:
+optional when installing LTTng-tools (which is always required). Note
+that:

 
 * You only need to install LTTng-modules if you intend to trace the
   Linux kernel.
 * You only need to install LTTng-UST if you intend to trace user
   applications.
 
 
 * You only need to install LTTng-modules if you intend to trace the
   Linux kernel.
 * You only need to install LTTng-UST if you intend to trace user
   applications.
 

-[role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions.
-|====
-|Distribution |Available in releases |Alternatives
-
-|Ubuntu
-|<<ubuntu,Ubuntu{nbsp}16.04 _Xenial Xerus_>>
-|LTTng{nbsp}2.8 for Ubuntu{nbsp}16.10 _Yakkety Yak_.
-
-LTTng{nbsp}{revision} for Ubuntu{nbsp}12.04 _Precise Pangolin_,
-Ubuntu{nbsp}14.04 _Trusty Tahr_, and Ubuntu{nbsp}16.04 _Xenial Xerus_:
-<<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Ubuntu releases.
-
-|Fedora
-|_Not available_
-|LTTng{nbsp}{revision} for Fedora{nbsp}25 and Fedora{nbsp}26 (not
-released yet).
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Fedora releases.
-
-|Debian
-|_Not available_
-|LTTng{nbsp}2.8 for Debian "stretch" (testing).
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Debian releases.
-
-|openSUSE
-|<<opensuse,openSUSE Leap{nbsp}42.1>>
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other openSUSE releases.
-
-|Arch Linux
-|_Not available_
-|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
-
-|Alpine Linux
-|_Not available_
-|LTTng{nbsp}2.8 for Alpine Linux "edge".
-
-LTTng{nbsp}2.8 for Alpine Linux{nbsp}3.5 (not released yet).
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Alpine Linux releases.
-
-|RHEL and SLES
-|See http://packages.efficios.com/[EfficiOS Enterprise Packages].
-|
-
-|Buildroot
-|<<"buildroot","Buildroot{nbsp}2016.02, Buildroot{nbsp}2016.05,
-and Buildroot{nbsp}2016.08">>
-|LTTng{nbsp}2.8 for Buildroot{nbsp}2016.11 (not released yet).
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Buildroot releases.
-
-|OpenEmbedded and Yocto
-|<<oe-yocto,Yocto Project{nbsp}2.1 _Krogoth_>> (`openembedded-core` layer)
-|LTTng{nbsp}2.8 for Yocto Project{nbsp}2.2 _Morty_.
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other Yocto releases.
-|====
-
-
-[[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
-Stable{nbsp}{revision} PPA>>.
-
-To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.04 _Xenial Xerus_:
-
-. Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-sudo apt-get install lttng-tools
-sudo apt-get install lttng-modules-dkms
-sudo 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"]
-----
-sudo 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"]
-----
-sudo apt-get install python3-lttngust
-----
---
-
-
-[[ubuntu-ppa]]
-==== noch:{LTTng} Stable {revision} PPA
-
-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}12.04 _Precise Pangolin_
-* Ubuntu{nbsp}14.04 _Trusty Tahr_
-* Ubuntu{nbsp}16.04 _Xenial Xerus_
-
-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:
-+
---
-[role="term"]
-----
-sudo apt-add-repository ppa:lttng/stable-2.7
-sudo apt-get update
-----
---
-
-. Install the main LTTng{nbsp}{revision} packages:
-+
---
-[role="term"]
-----
-sudo apt-get install lttng-tools
-sudo apt-get install lttng-modules-dkms
-sudo 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"]
-----
-sudo 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"]
-----
-sudo apt-get install python3-lttngust
-----
---
-
-
-[[opensuse]]
-=== noch:{openSUSE}/RPM
-
-To install LTTng{nbsp}{revision} on openSUSE Leap{nbsp}42.1:
-
-* 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.
-====
-
-
-[[buildroot]]
-=== Buildroot
-
-To install LTTng{nbsp}{revision} on Buildroot{nbsp}2016.02,
-Buildroot{nbsp}2016.05, or Buildroot{nbsp}2016.08:
-
-. 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**.
-
-
-[[oe-yocto]]
-=== OpenEmbedded and Yocto
-
-LTTng{nbsp}{revision} recipes are available in the
-http://layers.openembedded.org/layerindex/branch/master/layer/openembedded-core/[`openembedded-core`]
-layer for Yocto Project{nbsp}2.1 _Krogoth_ under the following names:
-
-* `lttng-tools`
-* `lttng-modules`
-* `lttng-ust`
-
-With BitBake, the simplest way to include LTTng recipes in your target
-image is to add them to `IMAGE_INSTALL_append` in path:{conf/local.conf}:
-
-----
-IMAGE_INSTALL_append = " lttng-tools lttng-modules lttng-ust"
-----
-
-If you use Hob:
-
-. Select a machine and an image recipe.
-. Click **Edit image recipe**.
-. Under the **All recipes** tab, search for **lttng**.
-. Check the desired LTTng recipes.
-
-[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
-
-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].
-

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


@@ -1617,7 +1344,7 @@ With so many similar terms, it's easy to get confused.
 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
 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
 like record the event's payload to a buffer.
 
 An **event record** is the representation of an event in a sub-buffer. A


@@ -1652,7 +1379,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)).


@@ -1948,7 +1675,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


@@ -2543,7 +2270,7 @@ holding more than one tracepoint providers.
 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
 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
 
 The `tracepoint()` macro takes at least two parameters: the tracepoint
 provider name and the tracepoint name. The corresponding tracepoint


@@ -2752,10 +2479,11 @@ In the following diagrams, we use the following file names:
 `libemon.so`::
   User library shared object file.
 
 `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.
 
 We assume that path:{.} is part of the env:LD_LIBRARY_PATH environment
 variable in the following instructions.


@@ -3204,7 +2932,7 @@ include::../common/ust-sit-step-tp-so.txt[]
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the

-  following line:
+  following lines:

 +
 --
 [source,c]
 +
 --
 [source,c]


@@ -3291,7 +3019,7 @@ include::../common/ust-sit-step-tp-so.txt[]
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the

-  following line:
+  following lines:

 +
 --
 [source,c]
 +
 --
 [source,c]


@@ -3440,7 +3168,7 @@ include::../common/ust-sit-step-tp-so.txt[]
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the

-  following line:
+  following lines:

 +
 --
 [source,c]
 +
 --
 [source,c]


@@ -3513,7 +3241,7 @@ include::../common/ust-sit-step-tp-so.txt[]
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the
 To build the instrumented user library:
 
 . In path:{emon.c}, before including path:{tpp.h}, add the

-  following line:
+  following lines:

 +
 --
 [source,c]
 +
 --
 [source,c]


@@ -4105,7 +3833,7 @@ lttng enable-event --userspace 'lttng_ust_tracelog:*'
 [[prebuilt-ust-helpers]]
 === Prebuilt user space tracing helpers
 
 [[prebuilt-ust-helpers]]
 === Prebuilt user space tracing helpers
 

-The LTTng-UST package provides a few helpers in the form or preloadable
+The LTTng-UST package provides a few helpers in the form of preloadable

 shared objects which automatically instrument system functions and
 calls.
 
 shared objects which automatically instrument system functions and
 calls.
 


@@ -4238,10 +3966,8 @@ Assuming no event record is lost, having only the function addresses on
 entry is enough to create a call graph, since an event record always
 contains the ID of the CPU that generated it.
 +
 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
 
 * **path:{liblttng-ust-cyg-profile.so}** is a more robust variant
 which also works in use cases where event records might get discarded or


@@ -4825,12 +4551,12 @@ MODULE_VERSION(__stringify(LTTNG_MODULES_MAJOR_VERSION) "."
 ----
 --
 
 ----
 --
 

-. 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]
   next to the existing ones:
 +
 --
 [source,make]

-.path:{probes/Makefile}
+.path:{probes/KBuild}

 ----
 # ...
 
 ----
 # ...
 


@@ -5140,7 +4866,7 @@ To output LTTng traces to a non-default location:
 --
 [role="term"]
 ----
 --
 [role="term"]
 ----

-lttng create --output=/tmp/some-directory my-session
+lttng create my-session --output=/tmp/some-directory

 ----
 --
 
 ----
 --
 


@@ -6032,7 +5758,7 @@ To use LTTng live:
 --
 [role="term"]
 ----
 --
 [role="term"]
 ----

-lttng create --live my-session
+lttng create my-session --live

 ----
 --
 +
 ----
 --
 +


@@ -6098,7 +5824,7 @@ To take a snapshot:
 --
 [role="term"]
 ----
 --
 [role="term"]
 ----

-lttng create --snapshot my-session
+lttng create my-session --snapshot

 ----
 --
 +
 ----
 --
 +


@@ -6198,7 +5924,7 @@ trace data after a system crash:
 --
 [role="term"]
 ----
 --
 [role="term"]
 ----

-lttng create --shm-path=/path/to/shm
+lttng create my-session -shm-path=/path/to/shm

 ----
 --
 
 ----
 --
 


@@ -6845,7 +6571,7 @@ event::
   or a Linux kernel KProbe.
 +
 An event is said to _occur_ at a specific time. Different actions can
   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>>::
 to a sub-buffer.
 
 <<channel-overwrite-mode-vs-discard-mode,event loss mode>>::