Update handling of perf counters in add-context

[lttng-tools.git] / doc / quickstart.txt

NOTES:
--------------
2011-07-21 : User-space tracer is not released. Tracing in user-space at this
point is not possible with lttng-tools.

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 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 http://lttng.org/lttng2.0 for more instructions for that part.
For user-space tracing, you'll need an instrumented application, please see
http://lttng.org/ust.

lttng-tools provide a session daemon (ltt-sessiond) that acts as a tracing
registry. To trace any instrumented applications or the kernel, a registered
tracing session is needed beforehand. To interact with the session daemon and a
tracing session, you should use the lttng command line UI (lttng).

Here is a list of some new 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

The next sections explain how to do tracing :)

Kernel Tracing
--------------

You have to modprobe the lttng-modules manually or the session daemon will do
it for you if those modules can be found on your system.

Again, you can then start the session daemon (ltt-sessiond) by hand or the
lttng command line tool will do it for you.

List possible kernel events:

# lttng list -k

1) Create a tracing session. A .lttngrc will be created 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 event(s). Here for example, we want only 'sched_switch' and
'sys_enter' events for the kernel (-k/--kernel).

# lttng enable-event sched_switch,sys_enter -k

or enable ALL events (-a/--all):

# lttng enable-event -a -k

3) 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 Kprobe (by Masami Hiramatsu) and data will be output in the trace
along side with your tracing data.

# lttng enable-event aname --kprobe symbol+0xffff7260695

or

# lttng enable-event aname --kprobe 0xffff7260695

Either an <address> or a <symbol+offset> can be used for kprobes.

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 --function <symbol_name>

4) 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 0

At this point, you will have to look at 'lttng add-context --help' for all
possible context type which are integer values.

You can on the same line activate multiple context:

# lttng add-context -k -e sched_switch -t 0 -t 2 -t 4

5) 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 define event:

# lttng add-context -k -e sched_switch -t perf --perf-type hw --perf-id cpu_cycles

You'll have to use the add-context help for all possible perf counter values.

6) Start tracing:

# lttng start

Tracing is in progress at this point and traces will be written in
$HOME/lttng-traces/mysession-<date>-<time>

7) Stop tracing:

# lttng stop

Note: At this point, you can restart the trace (lttng start), enable/disable
events or just go take a break and come back 3 days later to start it again :).

8) Destroy your session after you are done with tracing

# lttng destroy

See Reading a trace section below to read you trace(s).

User-space Tracing
--------------

User-space tracer 2.0 not released at this point. For the 0.x versions,
you need to use 'ustctl' to control user-space tracing.

Reading a trace
--------------

To read your trace, you can use babeltrace which will text dump your the
trace. Please see http://www.efficios.com/ctf and git tree
http://git.efficios.com/?p=babeltrace.git

# babeltrace -n $HOME/lttng-traces/mysession-<date>-<time> | less

Voilà!

Please report any bugs/comments on our mailing list
(ltt-dev@lists.casi.polymtl.ca) or you can go on our IRC channel at
irc.oftc.net, channel #lttng