NOTES:
--------------
2011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is
supported meaning that if you enable a tracepoint for user-space it will be
enabled for all applications for the current recording session you are working
on.
QUICKSTART
--------------
This is a quick start guide for the complete LTTng tool chain. This is divided
in three sections respectively kernel tracing, user-space tracing and reading a
trace.
See the README.adoc file for installation procedure or use the various Linux
distribution packages.
In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
installed. See https://lttng.org/lttng2.0 for more instructions for that part.
For user-space tracing, you'll need an instrumented application with lttng-ust
2.0.
lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing
registry. To trace any instrumented applications or the kernel, a registered
recording session is needed beforehand. To interact with the session daemon and a
recording session, you should use the lttng command line UI (lttng). It is also
possible to use the liblttngctl library for tracing control (lttng.h).
Here is a list of some powerful features the LTTng 2.0 kernel tracer offers:
* Kprobes support
* Function Tracer support
* Context information support (add context data to an event)
* Perf counter support
* Tracepoint support
And for the LTTng UST 2.0 tracer:
* Applications registration
* Automatic tracepoints activation upon app. registration
* Context information support
* Safe buffers after application crash
* Per-user tracing (root access *not* mandatory)
The next sections explains how to do tracing :)
Kernel Tracing
--------------
You can start the session daemon by invoking the command "lttng-sessiond", or
let the lttng command line tool do it for you. The session daemon loads the
LTTng tracer modules for you if those modules can be found on your system. If
they are not found, the kernel tracing feature will be unavailable.
List available kernel events:
# lttng list -k
1) Create a recording session. The .lttng directory will be created with .lttngrc
file in $HOME containing the session name (here 'mysession') you are working
on.
# lttng create mysession
If you have multiple sessions, you can change the current session by using
# lttng set-session myothersession
2) Enable all tracepoints and all system call events.
# lttng enable-event -a -k
3) Enable tracepoint event(s). Here for example, we want only
'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).
# lttng enable-event sched_switch,sched_wakeup -k
or enable ALL tracepoint events:
# lttng enable-event -a -k --tracepoint
4) Enable all system call event(s).
# lttng enable-event -a -k --syscall
5) Enable kprobes and/or the function tracer with lttng
This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
enable a dynamic probe and data will be output in the trace along side with
your tracing data.
# lttng enable-event aname -k --probe symbol+0x0
or
# lttng enable-event aname -k --probe 0xffff7260695
Either an
or a can be used for probes.
You can also enable function tracer, which uses the Ftrace API (by Steven
Rostedt). Again, data will be output in the trace.
# lttng enable-event aname -k --function
6) Enable context information for an event:
This is also a new feature which allows you to add context information to an
event. For example, you can add the PID along with the event information:
# lttng add-context -k -e sched_switch -t pid
At this point, you will have to look at 'lttng add-context --help' for all
possible context type.
You can on the same line activate multiple context:
# lttng add-context -k -e sched_switch -t pid -t nice -t tid
7) Enable perf counter for an event:
Again, a new powerful feature is the possibility to add perf counter data
(using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
event basis. Let say we want to get the CPU cycles at each event:
# lttng add-context -k -e sched_switch -t perf:cpu-cycles
You'll have to use the add-context help for all possible perf counter values.
8) Start tracing:
# lttng start
Tracing is in progress at this point and traces will be written in
$HOME/lttng-traces/mysession--