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