README.md

   1 LTTng-modules
   2 =============
   3
   4 _by [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)_
   5
   6
   7 LTTng kernel modules are Linux kernel modules which make
   8 [LTTng](http://lttng.org/) kernel tracing possible. They include
   9 essential control modules and many probes which instrument numerous
  10 interesting parts of Linux. LTTng-modules builds against a vanilla or
  11 distribution kernel, with no need for additional patches.
  12
  13 Other notable features:
  14
  15   - Produces [CTF](http://www.efficios.com/ctf)
  16     (Common Trace Format) natively.
  17   - Tracepoints, function tracer, CPU Performance Monitoring Unit (PMU)
  18     counters, kprobes, and kretprobes support.
  19   - Have the ability to attach _context_ information to events in the
  20     trace (e.g., any PMU counter, PID, PPID, TID, command name, etc).
  21     All the extra information fields to be collected with events are
  22     optional, specified on a per-tracing-session basis (except for
  23     timestamp and event ID, which are mandatory).
  24
  25
  26 Building
  27 --------
  28
  29 To build and install LTTng-modules, you will need to have your kernel
  30 headers available (or access to your full kernel source tree), and do:
  31
  32     make
  33     sudo make modules_install
  34     sudo depmod -a
  35
  36 The above commands will build LTTng-modules against your
  37 current kernel. If you need to build LTTng-modules against a custom
  38 kernel, do:
  39
  40     make KERNELDIR=/path/to/custom/kernel
  41     sudo make KERNELDIR=/path/to/custom/kernel modules_install
  42     sudo depmod -a kernel_version
  43
  44
  45 ### Required kernel config options
  46
  47 Make sure your target kernel has the following config options enabled:
  48
  49   - `CONFIG_MODULES`: loadable module support
  50   - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is
  51      necessary until the few required missing symbols are exported to GPL
  52      modules from mainline
  53   - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source
  54   - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation
  55      (enabled as a side-effect of any of the perf/ftrace/blktrace
  56      instrumentation features)
  57
  58
  59 ### Supported (optional) kernel config options
  60
  61 The following kernel configuration options will affect the features
  62 available from LTTng:
  63
  64   - `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing:
  65
  66         lttng enable-event -k --syscall
  67         lttng enable-event -k -a
  68
  69   - `CONFIG_PERF_EVENTS`: performance counters:
  70
  71         lttng add-context -t perf:*
  72
  73   - `CONFIG_EVENT_TRACING`: needed to allow block layer tracing
  74   - `CONFIG_KPROBES`: dynamic probes:
  75
  76         lttng enable-event -k --probe ...
  77
  78   - `CONFIG_KRETPROBES`: dynamic function entry/return probes:
  79
  80         lttng enable-event -k --function ...
  81
  82   - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
  83     number and name
  84
  85
  86 Using
  87 -----
  88
  89 Use [LTTng-tools](https://lttng.org/download) to control the tracer.
  90 The session daemon of LTTng-tools should automatically load the LTTng
  91 kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
  92 to print traces as a human-readable text log.
  93
  94
  95 Support
  96 -------
  97
  98 So far, it has been tested on various vanilla Linux kernels from 2.6.38
  99 to 3.16, most of them on IA-32/x86-64 and some of them on ARM and Power-PC
 100 32-bit. Linux 2.6.32 to 2.6.34 need up to 3 patches applied (refer to
 101 [`linux-patches`](linux-patches)). It should work fine with newer kernels and
 102 other architectures, but expect build issues with kernels older than 2.6.36.
 103
 104
 105 Notes
 106 -----
 107
 108 ### About perf PMU counters support
 109
 110 Each PMU counter has its zero value set when it is attached to a context with
 111 add-context. Therefore, it is normal that the same counters attached to both the
 112 stream context and event context show different values for a given event; what
 113 matters is that they increment at the same rate.