[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 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

The next sections explain how to do tracing :)

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

You can start the session daemon by invoking the command "ltt-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 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 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 (-a/--all):

# lttng enable-event -a -k

3) Enable all system call event(s).

# lttng enable-event -a -k --syscall

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

or

# lttng enable-event aname -k --probe 0xffff7260695

Either an <address> or a <symbol+offset> 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 <symbol_name>

5) 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 which are integer values.

You can on the same line activate multiple context:

# lttng add-context -k -e sched_switch -t pid -t nice -t tid

6) 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.

7) Start tracing:

# lttng start

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

8) 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 :).

9) 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
--------------

The tool "Babeltrace" can be used to dump your binary trace into a
human-readable text format. Please see
http://www.efficios.com/babeltrace 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
Commit	Line	Data
	1	NOTES:
	2	--------------
	3	2011-07-21 : User-space tracer is not released. Tracing in user-space at this
	4	point is not possible with lttng-tools.
	5
	6	QUICKSTART
	7	--------------
	8
	9	This is a quick start guide for the complete LTTng tool chain. This is divided
	10	in three sections respectively kernel tracing, user-space tracing and reading a
	11	trace.
	12
	13	See the README file for installation procedure or use the various Linux
	14	distribution packages.
	15
	16	In order to trace the kernel, you'll need the lttng-modules >= 2.0 compiled and
	17	installed. See http://lttng.org/lttng2.0 for more instructions for that part.
	18	For user-space tracing, you'll need an instrumented application, please see
	19	http://lttng.org/ust.
	20
	21	lttng-tools provide a session daemon (ltt-sessiond) that acts as a tracing
	22	registry. To trace any instrumented applications or the kernel, a registered
	23	tracing session is needed beforehand. To interact with the session daemon and a
	24	tracing session, you should use the lttng command line UI (lttng).
	25
	26	Here is a list of some powerful features the LTTng 2.0 kernel tracer offers:
	27
	28	* Kprobes support
	29	* Function Tracer support
	30	* Context information support (add context data to an event)
	31	* Perf counter support
	32	* Tracepoint support
	33
	34	The next sections explain how to do tracing :)
	35
	36	Kernel Tracing
	37	--------------
	38
	39	You can start the session daemon by invoking the command "ltt-sessiond",
	40	or let the lttng command line tool do it for you. The session daemon
	41	loads the LTTng tracer modules for you if those modules can be found on
	42	your system. If they are not found, the kernel tracing feature will be
	43	unavailable.
	44
	45	List available kernel events:
	46
	47	# lttng list -k
	48
	49	1) Create a tracing session. A .lttngrc will be created in $HOME containing
	50	the session name (here 'mysession') you are working on.
	51
	52	# lttng create mysession
	53
	54	If you have multiple sessions, you can change the current session by using
	55
	56	# lttng set-session myothersession
	57
	58	2) Enable tracepoint event(s). Here for example, we want only
	59	'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).
	60
	61	# lttng enable-event sched_switch,sched_wakeup -k
	62
	63	or enable ALL tracepoint events (-a/--all):
	64
	65	# lttng enable-event -a -k
	66
	67	3) Enable all system call event(s).
	68
	69	# lttng enable-event -a -k --syscall
	70
	71	4) Enable kprobes and/or the function tracer with lttng
	72
	73	This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
	74	enable a dynamic probe and data will be output in the trace along side with
	75	your tracing data.
	76
	77	# lttng enable-event aname -k --probe symbol+0xffff7260695
	78
	79	or
	80
	81	# lttng enable-event aname -k --probe 0xffff7260695
	82
	83	Either an <address> or a <symbol+offset> can be used for probes.
	84
	85	You can also enable function tracer, which uses the Ftrace API (by Steven
	86	Rostedt). Again, data will be output in the trace.
	87
	88	# lttng enable-event aname -k --function <symbol_name>
	89
	90	5) Enable context information for an event:
	91
	92	This is also a new feature which allows you to add context information to an
	93	event. For example, you can add the PID along with the event information:
	94
	95	# lttng add-context -k -e sched_switch -t pid
	96
	97	At this point, you will have to look at 'lttng add-context --help' for all
	98	possible context type which are integer values.
	99
	100	You can on the same line activate multiple context:
	101
	102	# lttng add-context -k -e sched_switch -t pid -t nice -t tid
	103
	104	6) Enable perf counter for an event:
	105
	106	Again, a new powerful feature is the possibility to add perf counter data
	107	(using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
	108	event basis. Let say we want to get the CPU cycles at each event:
	109
	110	# lttng add-context -k -e sched_switch -t perf:cpu-cycles
	111
	112	You'll have to use the add-context help for all possible perf counter values.
	113
	114	7) Start tracing:
	115
	116	# lttng start
	117
	118	Tracing is in progress at this point and traces will be written in
	119	$HOME/lttng-traces/mysession-<date>-<time>
	120
	121	8) Stop tracing:
	122
	123	# lttng stop
	124
	125	Note: At this point, you can restart the trace (lttng start), enable/disable
	126	events or just go take a break and come back 3 days later to start it again :).
	127
	128	9) Destroy your session after you are done with tracing
	129
	130	# lttng destroy
	131
	132	See Reading a trace section below to read you trace(s).
	133
	134	User-space Tracing
	135	--------------
	136
	137	User-space tracer 2.0 not released at this point. For the 0.x versions,
	138	you need to use 'ustctl' to control user-space tracing.
	139
	140	Reading a trace
	141	--------------
	142
	143	The tool "Babeltrace" can be used to dump your binary trace into a
	144	human-readable text format. Please see
	145	http://www.efficios.com/babeltrace and git tree
	146	http://git.efficios.com/?p=babeltrace.git
	147
	148	# babeltrace -n $HOME/lttng-traces/mysession-<date>-<time> \| less
	149
	150	Voilà!
	151
	152	Please report any bugs/comments on our mailing list
	153	(ltt-dev@lists.casi.polymtl.ca) or you can go on our IRC channel at
	154	irc.oftc.net, channel #lttng