Update quickstart, describing syscall events
[lttng-tools.git] / doc / quickstart.txt
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
This page took 0.04883 seconds and 5 git commands to generate.