Update handling of perf counters in add-context
[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
6f8eb304
DG
26Here is a list of some new powerful features the LTTng 2.0 kernel tracer
27offers:
28
29 * Kprobes support
30 * Function Tracer support
31 * Context information support (add context data to an event)
32 * Perf counter support
e7651054
DG
33
34The next sections explain how to do tracing :)
35
36Kernel Tracing
37--------------
38
39You have to modprobe the lttng-modules manually or the session daemon will do
6f8eb304 40it for you if those modules can be found on your system.
e7651054 41
6f8eb304
DG
42Again, you can then start the session daemon (ltt-sessiond) by hand or the
43lttng command line tool will do it for you.
e7651054
DG
44
45List possible kernel events:
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
e7651054
DG
582) Enable event(s). Here for example, we want only 'sched_switch' and
59'sys_enter' events for the kernel (-k/--kernel).
60
61# lttng enable-event sched_switch,sys_enter -k
62
63or enable ALL events (-a/--all):
64
65# lttng enable-event -a -k
66
6f8eb304
DG
673) Enable kprobes and/or the function tracer with lttng
68
69This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
70enable a Kprobe (by Masami Hiramatsu) and data will be output in the trace
71along side with your tracing data.
72
73# lttng enable-event aname --kprobe symbol+0xffff7260695
74
75or
76
77# lttng enable-event aname --kprobe 0xffff7260695
78
79Either an <address> or a <symbol+offset> can be used for kprobes.
80
81You can also enable function tracer, which uses the ftrace API (by Steven
82Rostedt). Again, data will be output in the trace.
83
84# lttng enable-event aname --function <symbol_name>
85
864) Enable context information for an event:
87
88This is also a new feature which allows you to add context information to an
89event. For example, you can add the PID along with the event information:
90
91# lttng add-context -k -e sched_switch -t 0
92
93At this point, you will have to look at 'lttng add-context --help' for all
94possible context type which are integer values.
95
96You can on the same line activate multiple context:
97
98# lttng add-context -k -e sched_switch -t 0 -t 2 -t 4
99
1005) Enable perf counter for an event:
101
102Again, a new powerful feature is the possibility to add perf counter data
90b9a268
DG
103(using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
104event basis. Let say we want to get the CPU cycles at each define event:
6f8eb304 105
90b9a268 106# lttng add-context -k -e sched_switch -t perf --perf-type hw --perf-id cpu_cycles
6f8eb304
DG
107
108You'll have to use the add-context help for all possible perf counter values.
109
1106) Start tracing:
e7651054
DG
111
112# lttng start
113
6f8eb304 114Tracing is in progress at this point and traces will be written in
e7651054
DG
115$HOME/lttng-traces/mysession-<date>-<time>
116
6f8eb304 1177) Stop tracing:
e7651054
DG
118
119# lttng stop
120
6f8eb304
DG
121Note: At this point, you can restart the trace (lttng start), enable/disable
122events or just go take a break and come back 3 days later to start it again :).
123
1248) Destroy your session after you are done with tracing
e7651054
DG
125
126# lttng destroy
127
6f8eb304
DG
128See Reading a trace section below to read you trace(s).
129
e7651054
DG
130User-space Tracing
131--------------
132
1aa502dd
MD
133User-space tracer 2.0 not released at this point. For the 0.x versions,
134you need to use 'ustctl' to control user-space tracing.
e7651054
DG
135
136Reading a trace
137--------------
138
1aa502dd
MD
139To read your trace, you can use babeltrace which will text dump your the
140trace. Please see http://www.efficios.com/ctf and git tree
e7651054
DG
141http://git.efficios.com/?p=babeltrace.git
142
143# babeltrace -n $HOME/lttng-traces/mysession-<date>-<time> | less
144
145VoilĂ !
6f8eb304
DG
146
147Please report any bugs/comments on our mailing list
148(ltt-dev@lists.casi.polymtl.ca) or you can go on our IRC channel at
149irc.oftc.net, channel #lttng
This page took 0.030325 seconds and 5 git commands to generate.