doc/quickstart.txt

   1 NOTES:
   2 --------------
   3
   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
   7 on.
   8
   9 QUICKSTART
  10 --------------
  11
  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
  14 trace.
  15
  16 See the README.md file for installation procedure or use the various Linux
  17 distribution packages.
  18
  19 In order to trace the kernel, you'll need the lttng-modules 2.0 compiled and
  20 installed. See https://lttng.org/lttng2.0 for more instructions for that part.
  21 For user-space tracing, you'll need an instrumented application with lttng-ust
  22 2.0.
  23
  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).
  29
  30 Here is a list of some powerful features the LTTng 2.0 kernel tracer offers:
  31
  32         * Kprobes support
  33         * Function Tracer support
  34         * Context information support (add context data to an event)
  35         * Perf counter support
  36         * Tracepoint support
  37
  38 And for the LTTng UST 2.0 tracer:
  39
  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)
  45
  46 The next sections explains how to do tracing :)
  47
  48 Kernel Tracing
  49 --------------
  50
  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.
  55
  56 List available kernel events:
  57
  58 # lttng list -k
  59
  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
  62 on.
  63
  64 # lttng create mysession
  65
  66 If you have multiple sessions, you can change the current session by using
  67
  68 # lttng set-session myothersession
  69
  70 2) Enable all tracepoints and all system call events.
  71
  72 # lttng enable-event -a -k
  73
  74 3) Enable tracepoint event(s). Here for example, we want only
  75 'sched_switch' and 'sched_wakeup' events for the kernel (-k/--kernel).
  76
  77 # lttng enable-event sched_switch,sched_wakeup -k
  78
  79 or enable ALL tracepoint events:
  80
  81 # lttng enable-event -a -k --tracepoint
  82
  83 4) Enable all system call event(s).
  84
  85 # lttng enable-event -a -k --syscall
  86
  87 5) Enable kprobes and/or the function tracer with lttng
  88
  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
  91 your tracing data.
  92
  93 # lttng enable-event aname -k --probe symbol+0x0
  94
  95 or
  96
  97 # lttng enable-event aname -k --probe 0xffff7260695
  98
  99 Either an <address> or a <symbol+offset> can be used for probes.
 100
 101 You can also enable function tracer, which uses the Ftrace API (by Steven
 102 Rostedt). Again, data will be output in the trace.
 103
 104 # lttng enable-event aname -k --function <symbol_name>
 105
 106 6) Enable context information for an event:
 107
 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:
 110
 111 # lttng add-context -k -e sched_switch -t pid
 112
 113 At this point, you will have to look at 'lttng add-context --help' for all
 114 possible context type.
 115
 116 You can on the same line activate multiple context:
 117
 118 # lttng add-context -k -e sched_switch -t pid -t nice -t tid
 119
 120 7) Enable perf counter for an event:
 121
 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:
 125
 126 # lttng add-context -k -e sched_switch -t perf:cpu-cycles
 127
 128 You'll have to use the add-context help for all possible perf counter values.
 129
 130 8) Start tracing:
 131
 132 # lttng start
 133
 134 Tracing is in progress at this point and traces will be written in
 135 $HOME/lttng-traces/mysession-<date>-<time>
 136
 137 NOTE: It will start tracing for *all* domain(s).
 138
 139 9) Stop tracing:
 140
 141 # lttng stop
 142
 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.
 146
 147 10) Destroy your session after you are done with tracing
 148
 149 # lttng destroy
 150
 151 See Reading a trace section below to read you trace(s).
 152
 153 User-space Tracing
 154 --------------
 155
 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.
 158
 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.
 162
 163 So, after instrumenting you applications with LTTng-ust 2.0
 164 (https://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.
 167
 168 Start your instrumented application at any time but at least before starting
 169 tracing :).
 170
 171 List available registered applications:
 172
 173 $ lttng list -u
 174
 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
 177 working on.
 178
 179 $ lttng create mysession
 180
 181 If you have multiple sessions, you can change the current session by using:
 182
 183 $ lttng set-session myothersession
 184
 185 2) Enable all tracepoints for the global UST domain ("-u" alone).
 186
 187 $ lttng enable-event -a -u
 188
 189 or enable a single tracepoint event.
 190
 191 $ lttng enable-event ust_tests_hello:tptest -u
 192
 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:
 195
 196 $ lttng add-context -t pid -e ust_tests_hello:tptest -u
 197
 198 At this point, you will have to look at 'lttng add-context --help' for all
 199 possible context type.
 200
 201 You can on the same line activate multiple context:
 202
 203 $ lttng add-context -u -e ust_tests_hello:tptest -t pid -t nice -t tid
 204
 205 4) Start tracing:
 206
 207 $ lttng start
 208
 209 Tracing is in progress at this point and traces will be written in the session
 210 directory.
 211
 212 NOTE: It will start tracing for *all* domain(s).
 213
 214 5) Stop tracing:
 215
 216 $ lttng stop
 217
 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.
 221
 222 6) Destroy your session after you are done with tracing
 223
 224 $ lttng destroy
 225
 226 See "Reading a trace" section below to read you trace(s).
 227
 228
 229 Reading a trace
 230 --------------
 231
 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
 235
 236 # babeltrace $HOME/lttng-traces/mysession-<date>-<time> | less
 237
 238 Voilà!
 239
 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