X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=2.8%2Flttng-docs-2.8.txt;h=fb3d2f6a68ca35a6313965261f198d67f0b5b26d;hb=cdd6b15373374828b7de42755b1c1e761b05ba2f;hp=ed0c9c6dd7cd2bf433ec9b84b5c535eba16a13c1;hpb=55e90f33b0503c68ef5e6e198c70db4d1ace4519;p=lttng-docs.git

diff --git a/2.8/lttng-docs-2.8.txt b/2.8/lttng-docs-2.8.txt
index ed0c9c6..fb3d2f6 100644
--- a/2.8/lttng-docs-2.8.txt
+++ b/2.8/lttng-docs-2.8.txt
@@ -1,7 +1,7 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
-v2.8, 25 October 2016
+v2.8, 2 December 2016
 
 
 include::../common/copyright.txt[]
@@ -372,67 +372,60 @@ but note that:
   applications.
 
 [role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 2 December 2016.
 |====
 |Distribution |Available in releases |Alternatives
 
-|Ubuntu
-|<<ubuntu,Ubuntu{nbsp}16.10 _Yakkety Yak_>>
+|https://www.ubuntu.com/[Ubuntu]
+|<<ubuntu,Ubuntu{nbsp}16.10 _Yakkety Yak_>>.
 |LTTng{nbsp}{revision} for Ubuntu{nbsp}14.04 _Trusty Tahr_
 and Ubuntu{nbsp}16.04 _Xenial Xerus_:
 <<ubuntu-ppa,use the LTTng Stable{nbsp}{revision} PPA>>.
 
+LTTng{nbsp}2.9 for Ubuntu{nbsp}14.04 _Trusty Tahr_
+and Ubuntu{nbsp}16.04 _Xenial Xerus_:
+link:/docs/v2.9#doc-ubuntu-ppa[use the LTTng Stable{nbsp}2.9 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
+|https://getfedora.org/[Fedora]
+|<<fedora,Fedora{nbsp}25>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
 other Fedora releases.
 
-|Debian
-|<<debian,Debian "stretch" (testing)>>
-|
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+|https://www.debian.org/[Debian]
+|<<debian,Debian "stretch" (testing)>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
 previous Debian releases.
 
-|openSUSE
+|https://www.opensuse.org/[openSUSE]
 |_Not available_
-|LTTng{nbsp}2.7 for openSUSE Leap{nbsp}42.1.
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
-other openSUSE releases.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>>.
 
-|Arch Linux
-|Latest AUR packages.
-|
+|https://www.archlinux.org/[Arch Linux]
+|_Not available_
+|link:/docs/v2.9#doc-arch-linux[LTTng{nbsp}2.9 from the AUR].
 
-|Alpine Linux
-|<<alpine-linux,Alpine Linux "edge">>
+|https://alpinelinux.org/[Alpine Linux]
+|<<alpine-linux,Alpine Linux "edge">>.
 |LTTng{nbsp}{revision} 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
+|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES]
 |See http://packages.efficios.com/[EfficiOS Enterprise Packages].
 |
 
-|Buildroot
-|_Not available_
-|LTTng{nbsp}{revision} for Buildroot{nbsp}2016.11 (not released yet).
-
-LTTng{nbsp}2.7 for Buildroot{nbsp}2016.02, Buildroot{nbsp}2016.05,
-and Buildroot{nbsp}2016.08.
-
-<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
+|https://buildroot.org/[Buildroot]
+|<<buildroot,Buildroot 2016.11>>.
+|<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
 other Buildroot releases.
 
-|OpenEmbedded and Yocto
-|<<oe-yocto,Yocto Project{nbsp}2.2 _Morty_>> (`openembedded-core` layer)
+|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and
+https://www.yoctoproject.org/[Yocto]
+|<<oe-yocto,Yocto Project{nbsp}2.2 _Morty_>> (`openembedded-core` layer).
 |<<building-from-source,Build LTTng{nbsp}{revision} from source>> for
 other OpenEmbedded releases.
 |====
@@ -445,7 +438,7 @@ LTTng{nbsp}{revision} is available on Ubuntu{nbsp}16.10 _Yakkety Yak_.
 For previous releases of Ubuntu, <<ubuntu-ppa,use the LTTng
 Stable{nbsp}{revision} PPA>>.
 
-To install LTTng{nbsp}{revision} on Ubuntu 16.10{nbsp}_Yakkety Yak_:
+To install LTTng{nbsp}{revision} on Ubuntu{nbsp}16.10 _Yakkety Yak_:
 
 . Install the main LTTng{nbsp}{revision} packages:
 +
@@ -470,7 +463,7 @@ sudo apt-get install liblttng-ust-agent-java
 --
 
 . **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:
 +
 --
@@ -527,7 +520,7 @@ sudo apt-get install liblttng-ust-agent-java
 --
 
 . **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:
 +
 --
@@ -538,6 +531,54 @@ sudo apt-get install python3-lttngust
 --
 
 
+[[fedora]]
+=== Fedora
+
+To install LTTng{nbsp}{revision} on Fedora{nbsp}25:
+
+. Install the LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision}
+  packages:
++
+--
+[role="term"]
+----
+sudo yum install lttng-tools
+sudo 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.8.tar.bz2 &&
+tar -xf lttng-modules-latest-2.8.tar.bz2 &&
+cd lttng-modules-2.8.* &&
+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 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.
+====
+
+
 [[debian]]
 === Debian
 
@@ -578,8 +619,8 @@ sudo apt-get install python3-lttngust
 [[alpine-linux]]
 === Alpine Linux
 
-To install LTTng{nbsp}{revision} (tracing control and user space
-tracing) on Alpine Linux "edge":
+To install LTTng-tools{nbsp}{revision} and LTTng-UST{nbsp}{revision} on
+Alpine Linux "edge":
 
 . Make sure your system is
   https://wiki.alpinelinux.org/wiki/Edge[configured for "edge"].
@@ -624,6 +665,36 @@ sudo depmod -a
 --
 
 
+[[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].
+
+
+[[buildroot]]
+=== Buildroot
+
+To install LTTng{nbsp}{revision} on Buildroot{nbsp}2016.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**.
+
+
 [[oe-yocto]]
 === OpenEmbedded and Yocto
 
@@ -666,14 +737,6 @@ LTTng-UST{nbsp}{revision} from source and pass the
 ====
 
 
-[[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
 
@@ -799,14 +862,15 @@ This tutorial walks you through the steps to:
 
 The following command lines start with cmd:sudo because you need root
 privileges to trace the Linux kernel. You can avoid using cmd:sudo if
-your Unix user is a member of the <<lttng-sessiond,tracing group>>.
+your Unix user is a member of the <<tracing-group,tracing group>>.
 
-. Create a <<tracing-session,tracing session>>:
+. Create a <<tracing-session,tracing session>> which writes its traces
+  to dir:{/tmp/my-kernel-trace}:
 +
 --
 [role="term"]
 ----
-sudo lttng create my-kernel-session
+sudo lttng create my-kernel-session --output=/tmp/my-kernel-trace
 ----
 --
 
@@ -816,20 +880,23 @@ sudo lttng create my-kernel-session
 [role="term"]
 ----
 lttng list --kernel
+lttng list --kernel --syscall
 ----
 --
 
-. Create an <<event,event rule>> which matches the desired event names,
-  for example `sched_switch` and `sched_process_fork`:
+. Create <<event,event rules>> which match the desired instrumentation
+  point names, for example the `sched_switch` and `sched_process_fork`
+  tracepoints, and the man:open(2) and man:close(2) system calls:
 +
 --
 [role="term"]
 ----
 sudo lttng enable-event --kernel sched_switch,sched_process_fork
+sudo lttng enable-event --kernel --syscall open,close
 ----
 --
 +
-You can also create an event rule which _matches_ all the Linux kernel
+You can also create an event rule which matches _all_ the Linux kernel
 tracepoints (this will generate a lot of data when tracing):
 +
 --
@@ -839,7 +906,7 @@ sudo lttng enable-event --kernel --all
 ----
 --
 
-. Start tracing:
+. <<basic-tracing-session-control,Start tracing>>:
 +
 --
 [role="term"]
@@ -850,7 +917,8 @@ sudo lttng start
 
 . Do some operation on your system for a few seconds. For example,
   load a website, or list the files of a directory.
-. Stop tracing and destroy the tracing session:
+. <<basic-tracing-session-control,Stop tracing>> and destroy the
+  tracing session:
 +
 --
 [role="term"]
@@ -863,10 +931,15 @@ sudo lttng destroy
 The man:lttng-destroy(1) command does not destroy the trace data; it
 only destroys the state of the tracing session.
 
-By default, LTTng saves the traces in
-+$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+,
-where +__name__+ is the tracing session name. Note that the
-env:LTTNG_HOME environment variable defaults to `$HOME` if not set.
+. For the sake of this example, make the recorded trace accessible to
+  the non-root users:
++
+--
+[role="term"]
+----
+sudo chown -R $(whoami) /tmp/my-kernel-trace
+----
+--
 
 See <<viewing-and-analyzing-your-traces,View and analyze the
 recorded events>> to view the recorded events.
@@ -1078,7 +1151,7 @@ lttng enable-event --userspace hello_world:my_first_tracepoint
 ----
 --
 
-. Start tracing:
+. <<basic-tracing-session-control,Start tracing>>:
 +
 --
 [role="term"]
@@ -1089,7 +1162,8 @@ lttng start
 
 . Go back to the running `hello` application and press Enter. The
   program executes all `tracepoint()` instrumentation points and exits.
-. Stop tracing and destroy the tracing session:
+. <<basic-tracing-session-control,Stop tracing>> and destroy the
+  tracing session:
 +
 --
 [role="term"]
@@ -1104,7 +1178,7 @@ only destroys the state of the tracing session.
 
 By default, LTTng saves the traces in
 +$LTTNG_HOME/lttng-traces/__name__-__date__-__time__+,
-where +__name__+ is the tracing session name. Note that the
+where +__name__+ is the tracing session name. The
 env:LTTNG_HOME environment variable defaults to `$HOME` if not set.
 
 See <<viewing-and-analyzing-your-traces,View and analyze the
@@ -1138,7 +1212,7 @@ Many tools are available to read LTTng traces:
 
 NOTE: This section assumes that the traces recorded during the previous
 tutorials were saved to their default location, in the
-dir:{$LTTNG_HOME/lttng-traces} directory. Note that the env:LTTNG_HOME
+dir:{$LTTNG_HOME/lttng-traces} directory. The env:LTTNG_HOME
 environment variable defaults to `$HOME` if not set.
 
 
@@ -1161,7 +1235,7 @@ further filtering:
 
 [role="term"]
 ----
-babeltrace ~/lttng-traces/my-kernel-session* | grep sys_
+babeltrace /tmp/my-kernel-trace | grep _switch
 ----
 
 You can pipe the output of cmd:babeltrace into a tool like man:wc(1) to
@@ -1169,7 +1243,7 @@ count the recorded events:
 
 [role="term"]
 ----
-babeltrace ~/lttng-traces/my-kernel-session* | grep sys_read | wc --lines
+babeltrace /tmp/my-kernel-trace | grep _open | wc --lines
 ----
 
 
@@ -1271,7 +1345,7 @@ Run this script:
 
 [role="term"]
 ----
-python3 top5proc.py ~/lttng-traces/my-kernel-session*/kernel
+python3 top5proc.py /tmp/my-kernel-trace/kernel
 ----
 
 Output example:
@@ -3290,7 +3364,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
-  following line:
+  following lines:
 +
 --
 [source,c]
@@ -3377,7 +3451,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
-  following line:
+  following lines:
 +
 --
 [source,c]
@@ -3526,7 +3600,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
-  following line:
+  following lines:
 +
 --
 [source,c]
@@ -3599,7 +3673,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
-  following line:
+  following lines:
 +
 --
 [source,c]
@@ -5017,8 +5091,8 @@ Any event that the LTTng logger emits is named `lttng_logger` and
 belongs to the Linux kernel <<domain,tracing domain>>. However, unlike
 other instrumentation points in the kernel tracing domain, **any Unix
 user** can <<enabling-disabling-events,create an event rule>> which
-matches its event name, not only the root user or users in the tracing
-group.
+matches its event name, not only the root user or users in the
+<<tracing-group,tracing group>>.
 
 To use the LTTng logger:
 
@@ -7276,7 +7350,7 @@ tracer::
 <<domain,tracing domain>>::
   A namespace for event sources.
 
-tracing group::
+<<tracing-group,tracing group>>::
   The Unix group in which a Unix user can be to be allowed to trace the
   Linux kernel.