The LTTng Documentation
=======================
Philippe Proulx <pproulx@efficios.com>
-v2.9, 2 December 2016
+v2.9, 8 December 2016
include::../common/copyright.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
privileges to trace the Linux kernel. You can avoid using cmd:sudo if
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
----
--
[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):
+
--
----
--
-. Start tracing:
+. <<basic-tracing-session-control,Start tracing>>:
+
--
[role="term"]
. 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"]
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.
----
--
-. Start tracing:
+. <<basic-tracing-session-control,Start tracing>>:
+
--
[role="term"]
. 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"]
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
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.
[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
[role="term"]
----
-babeltrace ~/lttng-traces/my-kernel-session* | grep sys_read | wc --lines
+babeltrace /tmp/my-kernel-trace | grep _open | wc --lines
----
[role="term"]
----
-python3 top5proc.py ~/lttng-traces/my-kernel-session*/kernel
+python3 top5proc.py /tmp/my-kernel-trace/kernel
----
Output example:
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 &&
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
----
====
+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
----
====
+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
----
====
+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
projects / lttng-docs.git / blobdiff