X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=2.9%2Flttng-docs-2.9.txt;h=ac3727e3942164c05270fde64bd2e163e83face6;hb=9f587ffca5db72b89ed21e3f8d51278b7d421d3a;hp=b72ebe652b436130180ba43fde6dc9c8392f26a9;hpb=7e35c9046df4437aecfcf05ab2178264afd461db;p=lttng-docs.git

diff --git a/2.9/lttng-docs-2.9.txt b/2.9/lttng-docs-2.9.txt
index b72ebe6..ac3727e 100644
--- a/2.9/lttng-docs-2.9.txt
+++ b/2.9/lttng-docs-2.9.txt
@@ -1,7 +1,7 @@
 The LTTng Documentation
 =======================
 Philippe Proulx <pproulx@efficios.com>
-v2.9, 29 November 2016
+v2.9, 8 December 2016
 
 
 include::../common/copyright.txt[]
@@ -74,6 +74,15 @@ include::../common/acknowledgements.txt[]
 [[whats-new]]
 == What's new in LTTng {revision}?
 
+LTTng{nbsp}{revision} bears the name _Joannès_. A Berliner Weisse style
+beer from the http://letreflenoir.com/[Trèfle Noir] microbrewery in
+https://en.wikipedia.org/wiki/Rouyn-Noranda[Rouyn-Noranda], the
+https://www.beeradvocate.com/beer/profile/20537/238967/[_**Joannès**_]
+is a tangy beer with a distinct pink dress and intense fruit flavor,
+thanks to the presence of fresh blackcurrant grown in Témiscamingue.
+
+New features and changes in LTTng{nbsp}{revision}:
+
 * **Tracing control**:
 ** You can override the name or the URL of a tracing session
    configuration when you use man:lttng-load(1) thanks to the new
@@ -331,11 +340,11 @@ but note that:
   applications.
 
 [role="growable"]
-.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 29 November 2016.
+.Availability of LTTng{nbsp}{revision} for major Linux distributions as of 2 December 2016.
 |====
 |Distribution |Available in releases |Alternatives
 
-|Ubuntu
+|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.8#doc-ubuntu[LTTng{nbsp}2.8 for Ubuntu{nbsp}16.10 _Yakkety Yak_].
@@ -343,26 +352,26 @@ but note that:
 <<building-from-source,Build LTTng{nbsp}{revision} from source>> for
 other Ubuntu releases.
 
-|Fedora
+|https://getfedora.org/[Fedora]
 |_Not available_
 |<<building-from-source,Build LTTng-modules{nbsp}{revision} from
 source>>.
 
-|Debian
+|https://www.debian.org/[Debian]
 |_Not available_
 |<<building-from-source,Build LTTng-modules{nbsp}{revision} from
 source>>.
 
-|openSUSE
+|https://www.opensuse.org/[openSUSE]
 |_Not available_
 |<<building-from-source,Build LTTng-modules{nbsp}{revision} from
 source>>.
 
-|Arch Linux
+|https://www.archlinux.org/[Arch Linux]
 |<<arch-linux,Latest AUR packages>>.
 |
 
-|Alpine Linux
+|https://alpinelinux.org/[Alpine Linux]
 |_Not available_
 |link:/docs/v2.8#doc-alpine-linux[LTTng{nbsp}2.8 for Alpine Linux{nbsp}"edge"].
 
@@ -371,18 +380,19 @@ 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
+|https://www.redhat.com/[RHEL] and https://www.suse.com/[SLES]
 |See http://packages.efficios.com/[EfficiOS Enterprise Packages].
 |
 
-|Buildroot
+|https://buildroot.org/[Buildroot]
 |_Not available_
-|LTTng{nbsp}2.8 for Buildroot{nbsp}2016.11 (not released yet).
+|link:/docs/v2.8#doc-buildroot[LTTng{nbsp}2.8 for Buildroot{nbsp}2016.11].
 
 <<building-from-source,Build LTTng{nbsp}{revision} from source>> for
 other Buildroot releases.
 
-|OpenEmbedded and Yocto
+|http://www.openembedded.org/wiki/Main_Page[OpenEmbedded] and
+https://www.yoctoproject.org/[Yocto]
 |_Not available_
 |link:/docs/v2.8#doc-oe-yocto[LTTng{nbsp}2.8 for Yocto Project{nbsp}2.2 _Morty_]
 (`openembedded-core` layer).
@@ -614,14 +624,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
 ----
 --
 
@@ -631,20 +642,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):
 +
 --
@@ -654,7 +668,7 @@ sudo lttng enable-event --kernel --all
 ----
 --
 
-. Start tracing:
+. <<basic-tracing-session-control,Start tracing>>:
 +
 --
 [role="term"]
@@ -665,7 +679,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"]
@@ -678,10 +693,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.
@@ -893,7 +913,7 @@ lttng enable-event --userspace hello_world:my_first_tracepoint
 ----
 --
 
-. Start tracing:
+. <<basic-tracing-session-control,Start tracing>>:
 +
 --
 [role="term"]
@@ -904,7 +924,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"]
@@ -919,7 +940,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
@@ -953,7 +974,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.
 
 
@@ -976,7 +997,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
@@ -984,7 +1005,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
 ----
 
 
@@ -1086,7 +1107,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:
@@ -3801,7 +3822,9 @@ wget http://lttng.org/files/lttng-tools/lttng-tools-latest-2.9.tar.bz2 &&
 tar -xf lttng-tools-latest-2.9.tar.bz2 &&
 cd lttng-tools-2.9.* &&
 ./configure --libdir=/usr/local/lib32 CFLAGS=-m32 CXXFLAGS=-m32 \
-            LDFLAGS='-L/usr/local/lib32 -L/usr/lib32' &&
+            LDFLAGS='-L/usr/local/lib32 -L/usr/lib32' \
+            --disable-bin-lttng --disable-bin-lttng-crash \
+            --disable-bin-lttng-relayd --disable-bin-lttng-sessiond &&
 make &&
 cd src/bin/lttng-consumerd &&
 sudo make install &&
@@ -4112,7 +4135,7 @@ The path:{liblttng-ust-cyg-profile*.so} helpers can add instrumentation
 to the entry and exit points of functions.
 
 man:gcc(1) and man:clang(1) have an option named
-https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html[`-finstrument-functions`]
+https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html[`-finstrument-functions`]
 which generates instrumentation calls for entry and exit to functions.
 The LTTng-UST function tracing helpers,
 path:{liblttng-ust-cyg-profile.so} and
@@ -4336,6 +4359,31 @@ lttng view
 ----
 ====
 
+In the resulting trace, an <<event,event record>> generated by a Java
+application using `java.util.logging` is named `lttng_jul:event` and
+has the following fields:
+
+`msg`::
+  Log record's message.
+
+`logger_name`::
+  Logger name.
+
+`class_name`::
+  Name of the class in which the log statement was executed.
+
+`method_name`::
+  Name of the method in which the log statement was executed.
+
+`long_millis`::
+  Logging time (timestamp in milliseconds).
+
+`int_loglevel`::
+  Log level integer value.
+
+`int_threadid`::
+  ID of the thread in which the log statement was executed.
+
 You can use the opt:lttng-enable-event(1):--loglevel or
 opt:lttng-enable-event(1):--loglevel-only option of the
 man:lttng-enable-event(1) command to target a range of JUL log levels
@@ -4484,6 +4532,37 @@ lttng view
 ----
 ====
 
+In the resulting trace, an <<event,event record>> generated by a Java
+application using log4j is named `lttng_log4j:event` and
+has the following fields:
+
+`msg`::
+  Log record's message.
+
+`logger_name`::
+  Logger name.
+
+`class_name`::
+  Name of the class in which the log statement was executed.
+
+`method_name`::
+  Name of the method in which the log statement was executed.
+
+`filename`::
+  Name of the file in which the executed log statement is located.
+
+`line_number`::
+  Line number at which the log statement was executed.
+
+`timestamp`::
+  Logging timestamp.
+
+`int_loglevel`::
+  Log level integer value.
+
+`thread_name`::
+  Name of the Java thread in which the log statement was executed.
+
 You can use the opt:lttng-enable-event(1):--loglevel or
 opt:lttng-enable-event(1):--loglevel-only option of the
 man:lttng-enable-event(1) command to target a range of Apache log4j log levels
@@ -4803,6 +4882,33 @@ lttng view
 ----
 ====
 
+In the resulting trace, an <<event,event record>> generated by a Python
+application is named `lttng_python:event` and has the following fields:
+
+`asctime`::
+  Logging time (string).
+
+`msg`::
+  Log record's message.
+
+`logger_name`::
+  Logger name.
+
+`funcName`::
+  Name of the function in which the log statement was executed.
+
+`lineno`::
+  Line number at which the log statement was executed.
+
+`int_loglevel`::
+  Log level integer value.
+
+`thread`::
+  ID of the Python thread in which the log statement was executed.
+
+`threadName`::
+  Name of the Python thread in which the log statement was executed.
+
 You can use the opt:lttng-enable-event(1):--loglevel or
 opt:lttng-enable-event(1):--loglevel-only option of the
 man:lttng-enable-event(1) command to target a range of Python log levels
@@ -4850,8 +4956,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:
 
@@ -7267,7 +7373,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.