doc/quickstart.txt

   1 QUICKSTART
   2 --------------
   3
   4 This is a quick start guide for the complete LTTng tool chain. This is divided
   5 in three sections respectively Kernel tracing, user-space tracing and reading a
   6 trace.
   7
   8 See the README file for installation procedure or use the various Linux
   9 distribution packages.
  10
  11 In order to trace the Kernel, you'll need the lttng-modules >= 2.0 compiled and
  12 installed. See http://lttng.org/content/lttng-kernel-tracer for more
  13 instructions for that part. For user-space tracing, you'll need an instrumented
  14 application, please see http://lttng.org/ust
  15
  16 lttng-tools provide a session daemon (ltt-sessiond) that acts as a tracing
  17 registry. To trace any instrumented applications or the kernel, a registered
  18 tracing session is needed.
  19
  20 To interact with the session daemon and a tracing session, you can use the
  21 lttng command line UI (lttng).
  22
  23 The next sections explain how to do tracing :)
  24
  25 Kernel Tracing
  26 --------------
  27
  28 You have to modprobe the lttng-modules manually or the session daemon will do
  29 it for you if they can be found on your system.
  30
  31 You can then start the session daemon by hand or the lttng command line tool
  32 will do it for you.
  33
  34 List possible kernel events:
  35
  36 # lttng list -k
  37
  38 1) Create a tracing session. A .lttngrc will be created in $HOME containing
  39 the session name (here 'mysession') you are working on.
  40
  41 # lttng create mysession
  42
  43 2) Enable event(s). Here for example, we want only 'sched_switch' and
  44 'sys_enter' events for the kernel (-k/--kernel).
  45
  46 # lttng enable-event sched_switch,sys_enter -k
  47
  48 or enable ALL events (-a/--all):
  49
  50 # lttng enable-event -a -k
  51
  52 3) Start tracing:
  53
  54 # lttng start
  55
  56 Tracing is in progress at this point and will be written in
  57 $HOME/lttng-traces/mysession-<date>-<time>
  58
  59 4) Stop tracing:
  60
  61 # lttng stop
  62
  63 5) Destroy your session after you are done with tracing
  64
  65 # lttng destroy
  66
  67 User-space Tracing
  68 --------------
  69
  70 User-space tracer 2.0 not released at this point. For the 0.x versions,
  71 you need to use 'ustctl' to control user-space tracing.
  72
  73 Reading a trace
  74 --------------
  75
  76 To read your trace, you can use babeltrace which will text dump your the
  77 trace. Please see http://www.efficios.com/ctf and git tree
  78 http://git.efficios.com/?p=babeltrace.git
  79
  80 # babeltrace -n $HOME/lttng-traces/mysession-<date>-<time> | less
  81
  82 Voilà!