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