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 (lttng-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 "lttng-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 all tracepoints and all system call events.
  59
  60 # lttng enable-event -a -k
  61
  62 3) Enable tracepoint event(s). Here for example, we want only
  63 'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).
  64
  65 # lttng enable-event sched_switch,sched_wakeup -k
  66
  67 or enable ALL tracepoint events:
  68
  69 # lttng enable-event -a -k --tracepoint
  70
  71 4) Enable all system call event(s).
  72
  73 # lttng enable-event -a -k --syscall
  74
  75 5) Enable kprobes and/or the function tracer with lttng
  76
  77 This is a new feature made possible by the new LTTng 2.0 kernel tracer. You can
  78 enable a dynamic probe and data will be output in the trace along side with
  79 your tracing data.
  80
  81 # lttng enable-event aname -k --probe symbol+0x0
  82
  83 or
  84
  85 # lttng enable-event aname -k --probe 0xffff7260695
  86
  87 Either an <address> or a <symbol+offset> can be used for probes.
  88
  89 You can also enable function tracer, which uses the Ftrace API (by Steven
  90 Rostedt). Again, data will be output in the trace.
  91
  92 # lttng enable-event aname -k --function <symbol_name>
  93
  94 6) Enable context information for an event:
  95
  96 This is also a new feature which allows you to add context information to an
  97 event. For example, you can add the PID along with the event information:
  98
  99 # lttng add-context -k -e sched_switch -t pid
 100
 101 At this point, you will have to look at 'lttng add-context --help' for all
 102 possible context type which are integer values.
 103
 104 You can on the same line activate multiple context:
 105
 106 # lttng add-context -k -e sched_switch -t pid -t nice -t tid
 107
 108 7) Enable perf counter for an event:
 109
 110 Again, a new powerful feature is the possibility to add perf counter data
 111 (using the perf API by Ingo Molnar and Thomas Gleixner) to the trace on a per
 112 event basis. Let say we want to get the CPU cycles at each event:
 113
 114 # lttng add-context -k -e sched_switch -t perf:cpu-cycles
 115
 116 You'll have to use the add-context help for all possible perf counter values.
 117
 118 8) Start tracing:
 119
 120 # lttng start
 121
 122 Tracing is in progress at this point and traces will be written in
 123 $HOME/lttng-traces/mysession-<date>-<time>
 124
 125 9) Stop tracing:
 126
 127 # lttng stop
 128
 129 Note: At this point, you can restart the trace (lttng start), enable/disable
 130 events or just go take a break and come back 3 days later to start it again :).
 131
 132 10) Destroy your session after you are done with tracing
 133
 134 # lttng destroy
 135
 136 See Reading a trace section below to read you trace(s).
 137
 138 User-space Tracing
 139 --------------
 140
 141 User-space tracer 2.0 not released at this point. For the 0.x versions,
 142 you need to use 'ustctl' to control user-space tracing.
 143
 144 Reading a trace
 145 --------------
 146
 147 The tool "Babeltrace" can be used to dump your binary trace into a
 148 human-readable text format. Please see
 149 http://www.efficios.com/babeltrace and git tree
 150 http://git.efficios.com/?p=babeltrace.git
 151
 152 # babeltrace $HOME/lttng-traces/mysession-<date>-<time> | less
 153
 154 Voilà!
 155
 156 Please report any bugs/comments on our mailing list
 157 (ltt-dev@lists.casi.polymtl.ca) or you can go on our IRC channel at
 158 irc.oftc.net, channel #lttng