4 2011-12-12: For user-space tracing, only the global UST domain ("-u" alone) is
5 supported meaning that if you enable a tracepoint for user-space it will be
6 enabled for all applications for the current tracing session you are working
12 This is a quick start guide for the complete LTTng tool chain. This is divided
13 in three sections respectively kernel tracing, user-space tracing and reading a
16 See the README.md file for installation procedure or use the various Linux
17 distribution packages.
19 In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
20 installed. See http://lttng.org/lttng2.0 for more instructions for that part.
21 For user-space tracing, you'll need an instrumented application with lttng-ust
24 lttng-tools provide a session daemon (lttng-sessiond) that acts as a tracing
25 registry. To trace any instrumented applications or the kernel, a registered
26 tracing session is needed beforehand. To interact with the session daemon and a
27 tracing session, you should use the lttng command line UI (lttng). It is also
28 possible to use the liblttngctl library for tracing control (lttng.h).
30 Here is a list of some powerful features the LTTng 2.0 kernel tracer offers:
33 * Function Tracer support
34 * Context information support (add context data to an event)
35 * Perf counter support
38 And for the LTTng UST 2.0 tracer:
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)
46 The next sections explains how to do tracing :)
51 You can start the session daemon by invoking the command "lttng-sessiond", or
52 let the lttng command line tool do it for you. The session daemon loads the
53 LTTng tracer modules for you if those modules can be found on your system. If
54 they are not found, the kernel tracing feature will be unavailable.
56 List available kernel events:
60 1) Create a tracing session. The .lttng directory will be created with .lttngrc
61 file in $HOME containing the session name (here 'mysession') you are working
64 # lttng create mysession
66 If you have multiple sessions, you can change the current session by using
68 # lttng set-session myothersession
70 2) Enable all tracepoints and all system call events.
72 # lttng enable-event -a -k
74 3) Enable tracepoint event(s). Here for example, we want only
75 'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).
77 # lttng enable-event sched_switch,sched_wakeup -k
79 or enable ALL tracepoint events:
81 # lttng enable-event -a -k --tracepoint
83 4) Enable all system call event(s).
85 # lttng enable-event -a -k --syscall
87 5) Enable kprobes and/or the function tracer with lttng
89 This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
90 enable a dynamic probe and data will be output in the trace along side with
93 # lttng enable-event aname -k --probe symbol+0x0
97 # lttng enable-event aname -k --probe 0xffff7260695
99 Either an <address> or a <symbol+offset> can be used for probes.
101 You can also enable function tracer, which uses the Ftrace API (by Steven
102 Rostedt). Again, data will be output in the trace.
104 # lttng enable-event aname -k --function <symbol_name>
106 6) Enable context information for an event:
108 This is also a new feature which allows you to add context information to an
109 event. For example, you can add the PID along with the event information:
111 # lttng add-context -k -e sched_switch -t pid
113 At this point, you will have to look at 'lttng add-context --help' for all
114 possible context type.
116 You can on the same line activate multiple context:
118 # lttng add-context -k -e sched_switch -t pid -t nice -t tid
120 7) Enable perf counter for an event:
122 Again, a new powerful feature is the possibility to add perf counter data
123 (using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
124 event basis. Let say we want to get the CPU cycles at each event:
126 # lttng add-context -k -e sched_switch -t perf:cpu-cycles
128 You'll have to use the add-context help for all possible perf counter values.
134 Tracing is in progress at this point and traces will be written in
135 $HOME/lttng-traces/mysession-<date>-<time>
137 NOTE: It will start tracing for *all* domain(s).
143 NOTE: At this point, you can restart the trace (lttng start), enable/disable
144 events or just go take a break and come back 3 days later to start it again :).
145 You can also read the trace since the buffers are flushed on stop command.
147 10) Destroy your session after you are done with tracing
151 See Reading a trace section below to read you trace(s).
156 Like 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.
159 NOTE: You do *not* need root credentials in order to tracer user-space
160 applications. However, if you run the session daemon under non-root user
161 rights, only applications of that user will be traced.
163 So, after instrumenting you applications with LTTng-ust 2.0
164 (http://lttng.org/lttng2.0), upon startup, it will automatically register to
165 the session daemon. If there is none running, it will simply wait on a seperate
166 thread for a session daemon to appear and then register.
168 Start your instrumented application at any time but at least before starting
171 List available registered applications:
175 1) 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
179 $ lttng create mysession
181 If you have multiple sessions, you can change the current session by using:
183 $ lttng set-session myothersession
185 2) Enable all tracepoints for the global UST domain ("-u" alone).
187 $ lttng enable-event -a -u
189 or enable a single tracepoint event.
191 $ lttng enable-event ust_tests_hello:tptest -u
193 3) This is also a new feature which allows you to add context information to an
194 event. For example, you can add the PID along with the event information:
196 $ lttng add-context -t pid -e ust_tests_hello:tptest -u
198 At this point, you will have to look at 'lttng add-context --help' for all
199 possible context type.
201 You can on the same line activate multiple context:
203 $ lttng add-context -u -e ust_tests_hello:tptest -t pid -t nice -t tid
209 Tracing is in progress at this point and traces will be written in the session
212 NOTE: It will start tracing for *all* domain(s).
218 NOTE: At this point, you can restart the trace (lttng start), enable/disable
219 events or just go take a break and come back 3 days later to start it again :).
220 You can also read the trace since the buffers are flushed on stop command.
222 6) Destroy your session after you are done with tracing
226 See "Reading a trace" section below to read you trace(s).
232 The tool "Babeltrace" can be used to dump your binary trace into a
233 human-readable text format. Please see http://www.efficios.com/babeltrace and
234 git tree http://git.efficios.com/?p=babeltrace.git
236 # babeltrace $HOME/lttng-traces/mysession-<date>-<time> | less
240 Please report any bugs/comments on our mailing list (lttng-dev@lists.lttng.org)
241 or you can go on our IRC channel at irc.oftc.net, channel #lttng