Modernize README with Markdown
[lttng-tools.git] / doc / quickstart.txt
CommitLineData
6f8eb304
DG
1NOTES:
2--------------
9bb12755
DG
3
42011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is
5supported meaning that if you enable a tracepoint for user-space it will be
6enabled for all applications for the current tracing session you are working
7on.
6f8eb304 8
e7651054
DG
9QUICKSTART
10--------------
11
12This is a quick start guide for the complete LTTng tool chain. This is divided
6f8eb304 13in three sections respectively kernel tracing, user-space tracing and reading a
e7651054
DG
14trace.
15
adf4e918 16See the README.md file for installation procedure or use the various Linux
e7651054
DG
17distribution packages.
18
9bb12755 19In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
6f8eb304 20installed. See http://lttng.org/lttng2.0 for more instructions for that part.
9bb12755
DG
21For user-space tracing, you'll need an instrumented application with lttng-ust
222.0.
e7651054 23
32258573 24lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing
e7651054 25registry. To trace any instrumented applications or the kernel, a registered
6f8eb304 26tracing session is needed beforehand. To interact with the session daemon and a
9bb12755
DG
27tracing session, you should use the lttng command line UI (lttng). It is also
28possible to use the liblttngctl library for tracing control (lttng.h).
e7651054 29
617d7d15 30Here is a list of some powerful features the LTTng 2.0 kernel tracer offers:
6f8eb304
DG
31
32 * Kprobes support
33 * Function Tracer support
34 * Context information support (add context data to an event)
35 * Perf counter support
617d7d15 36 * Tracepoint support
e7651054 37
9bb12755
DG
38And for the LTTng UST 2.0 tracer:
39
40 * Applications registration
41 * Automatic tracepoints activation upon app. registration
42 * Context information support
43 * Safe buffers after application crash
44 * Per-user tracing (root access *not* mandatory)
45
46The next sections explains how to do tracing :)
e7651054
DG
47
48Kernel Tracing
49--------------
50
9bb12755
DG
51You can start the session daemon by invoking the command "lttng-sessiond", or
52let the lttng command line tool do it for you. The session daemon loads the
53LTTng tracer modules for you if those modules can be found on your system. If
54they are not found, the kernel tracing feature will be unavailable.
e7651054 55
495c67f5 56List available kernel events:
e7651054
DG
57
58# lttng list -k
59
9bb12755
DG
601) Create a tracing session. The .lttng directory will be created with .lttngrc
61file in $HOME containing the session name (here 'mysession') you are working
62on.
e7651054
DG
63
64# lttng create mysession
65
6f8eb304
DG
66If you have multiple sessions, you can change the current session by using
67
68# lttng set-session myothersession
69
cd84aa76
MD
702) Enable all tracepoints and all system call events.
71
72# lttng enable-event -a -k
73
743) Enable tracepoint event(s). Here for example, we want only
4bc385dd 75'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).
e7651054 76
4bc385dd 77# lttng enable-event sched_switch,sched_wakeup -k
e7651054 78
cd84aa76 79or enable ALL tracepoint events:
e7651054 80
cd84aa76 81# lttng enable-event -a -k --tracepoint
e7651054 82
cd84aa76 834) Enable all system call event(s).
4bc385dd
MD
84
85# lttng enable-event -a -k --syscall
86
cd84aa76 875) Enable kprobes and/or the function tracer with lttng
6f8eb304
DG
88
89This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
617d7d15
MD
90enable a dynamic probe and data will be output in the trace along side with
91your tracing data.
6f8eb304 92
7a3d1328 93# lttng enable-event aname -k --probe symbol+0x0
6f8eb304
DG
94
95or
96
975fdf53 97# lttng enable-event aname -k --probe 0xffff7260695
6f8eb304 98
617d7d15 99Either an <address> or a <symbol+offset> can be used for probes.
6f8eb304 100
617d7d15 101You can also enable function tracer, which uses the Ftrace API (by Steven
6f8eb304
DG
102Rostedt). Again, data will be output in the trace.
103
975fdf53 104# lttng enable-event aname -k --function <symbol_name>
6f8eb304 105
cd84aa76 1066) Enable context information for an event:
6f8eb304
DG
107
108This is also a new feature which allows you to add context information to an
109event. For example, you can add the PID along with the event information:
110
617d7d15 111# lttng add-context -k -e sched_switch -t pid
6f8eb304
DG
112
113At this point, you will have to look at 'lttng add-context --help' for all
9bb12755 114possible context type.
6f8eb304
DG
115
116You can on the same line activate multiple context:
117
617d7d15 118# lttng add-context -k -e sched_switch -t pid -t nice -t tid
6f8eb304 119
cd84aa76 1207) Enable perf counter for an event:
6f8eb304
DG
121
122Again, a new powerful feature is the possibility to add perf counter data
90b9a268 123(using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
617d7d15 124event basis. Let say we want to get the CPU cycles at each event:
6f8eb304 125
617d7d15 126# lttng add-context -k -e sched_switch -t perf:cpu-cycles
6f8eb304
DG
127
128You'll have to use the add-context help for all possible perf counter values.
129
cd84aa76 1308) Start tracing:
e7651054
DG
131
132# lttng start
133
6f8eb304 134Tracing is in progress at this point and traces will be written in
e7651054
DG
135$HOME/lttng-traces/mysession-<date>-<time>
136
9bb12755
DG
137NOTE: It will start tracing for *all* domain(s).
138
cd84aa76 1399) Stop tracing:
e7651054
DG
140
141# lttng stop
142
9bb12755 143NOTE: At this point, you can restart the trace (lttng start), enable/disable
6f8eb304 144events or just go take a break and come back 3 days later to start it again :).
9bb12755 145You can also read the trace since the buffers are flushed on stop command.
6f8eb304 146
cd84aa76 14710) Destroy your session after you are done with tracing
e7651054
DG
148
149# lttng destroy
150
6f8eb304
DG
151See Reading a trace section below to read you trace(s).
152
e7651054
DG
153User-space Tracing
154--------------
155
9bb12755
DG
156Like kernel tracing, you can start the session daemon by invoking the command
157"lttng-sessiond", or let the lttng command line tool do it for you.
158
159NOTE: You do *not* need root credentials in order to tracer user-space
160applications. However, if you run the session daemon under non-root user
161rights, only applications of that user will be traced.
162
163So, after instrumenting you applications with LTTng-ust 2.0
164(http://lttng.org/lttng2.0), upon startup, it will automatically register to
165the session daemon. If there is none running, it will simply wait on a seperate
166thread for a session daemon to appear and then register.
167
168Start your instrumented application at any time but at least before starting
169tracing :).
170
171List available registered applications:
172
173$ lttng list -u
174
1751) Create a tracing session. The .lttng directory will be created with a
176.lttngrc file in $HOME containing the session name (here 'mysession') you are
177working on.
178
179$ lttng create mysession
180
181If you have multiple sessions, you can change the current session by using:
182
183$ lttng set-session myothersession
184
1852) Enable all tracepoints for the global UST domain ("-u" alone).
186
187$ lttng enable-event -a -u
188
189or enable a single tracepoint event.
190
191$ lttng enable-event ust_tests_hello:tptest -u
192
1933) This is also a new feature which allows you to add context information to an
194event. For example, you can add the PID along with the event information:
195
196$ lttng add-context -t pid -e ust_tests_hello:tptest -u
197
198At this point, you will have to look at 'lttng add-context --help' for all
199possible context type.
200
201You can on the same line activate multiple context:
202
203$ lttng add-context -u -e ust_tests_hello:tptest -t pid -t nice -t tid
204
2054) Start tracing:
206
207$ lttng start
208
6bf5e7c9
DG
209Tracing is in progress at this point and traces will be written in the session
210directory.
9bb12755
DG
211
212NOTE: It will start tracing for *all* domain(s).
213
2145) Stop tracing:
215
216$ lttng stop
217
218NOTE: At this point, you can restart the trace (lttng start), enable/disable
219events or just go take a break and come back 3 days later to start it again :).
220You can also read the trace since the buffers are flushed on stop command.
221
2226) Destroy your session after you are done with tracing
223
224$ lttng destroy
225
226See "Reading a trace" section below to read you trace(s).
227
e7651054
DG
228
229Reading a trace
230--------------
231
b79f82bb 232The tool "Babeltrace" can be used to dump your binary trace into a
9bb12755
DG
233human-readable text format. Please see http://www.efficios.com/babeltrace and
234git tree http://git.efficios.com/?p=babeltrace.git
e7651054 235
9674ce7a 236# babeltrace $HOME/lttng-traces/mysession-<date>-<time> | less
e7651054
DG
237
238VoilĂ !
6f8eb304 239
9bb12755
DG
240Please report any bugs/comments on our mailing list (lttng-dev@lists.lttng.org)
241or you can go on our IRC channel at irc.oftc.net, channel #lttng
This page took 0.06008 seconds and 4 git commands to generate.