README

   1 LTTng 2.x modules
   2
   3 Mathieu Desnoyers
   4 March 29, 2013
   5
   6 LTTng 2.x kernel modules build against a vanilla or distribution kernel, without
   7 need for additional patches. Other features:
   8
   9 - Produces CTF (Common Trace Format) natively,
  10   (http://www.efficios.com/ctf)
  11 - Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
  12   counters, kprobes, and kretprobes support,
  13 - Integrated interface for both kernel and userspace tracing,
  14 - Have the ability to attach "context" information to events in the
  15   trace (e.g. any PMU counter, pid, ppid, tid, comm name, etc).
  16   All the extra information fields to be collected with events are
  17   optional, specified on a per-tracing-session basis (except for
  18   timestamp and event id, which are mandatory).
  19
  20 To build and install, you will need to have your kernel headers available (or
  21 access to your full kernel source tree), and use:
  22
  23 % make
  24 # make modules_install
  25 # depmod -a
  26
  27 If you need to specify the target directory to the kernel you want to build
  28 against, use:
  29
  30 % KERNELDIR=path_to_kernel_dir make
  31 # KERNELDIR=path_to_kernel_dir make modules_install
  32 # depmod -a kernel_version
  33
  34 Use lttng-tools to control the tracer. LTTng tools should automatically load
  35 the kernel modules when needed. Use Babeltrace to print traces as a
  36 human-readable text log. These tools are available at the following URL:
  37 http://lttng.org/lttng2.0
  38
  39 Linux kernels >= 2.6.36 are supported.
  40
  41
  42 * Kernel config options required
  43
  44 CONFIG_MODULES: required
  45   * Kernel modules support.
  46 CONFIG_KALLSYMS: required
  47   * See wrapper/ files. This is necessary until the few required missing
  48     symbols are exported to GPL modules from mainline.
  49 CONFIG_HIGH_RES_TIMERS: required
  50   * Needed for LTTng 2.0 clock source.
  51 CONFIG_TRACEPOINTS: required
  52     kernel tracepoint instrumentation
  53     * Enabled as side-effect of any of the perf/ftrace/blktrace
  54       instrumentation features.
  55
  56
  57 * Kernel config options supported (optional)
  58
  59 The following kernel configuration options will affect the features
  60 available from LTTng:
  61
  62
  63 CONFIG_HAVE_SYSCALL_TRACEPOINTS:
  64             system call tracing
  65                lttng enable-event -k --syscall
  66                lttng enable-event -k -a
  67 CONFIG_PERF_EVENTS:
  68             performance counters
  69                lttng add-context -t perf:*
  70 CONFIG_EVENT_TRACING:
  71             needed to allow block layer tracing
  72 CONFIG_KPROBES:
  73             Dynamic probe.
  74                lttng enable-event -k --probe ...
  75 CONFIG_KRETPROBES:
  76             Dynamic function entry/return probe.
  77                lttng enable-event -k --function ...
  78 CONFIG_KALLSYMS_ALL:
  79             State dump of mapping between block device number and name.
  80
  81
  82 * Note about Perf PMU counters support
  83
  84 Each PMU counter has its zero value set when it is attached to a context with
  85 add-context. Therefore, it is normal that the same counters attached to both the
  86 stream context and event context show different values for a given event; what
  87 matters is that they increment at the same rate.