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 ### Kernel built-in support
  46
  47 It is also possible to build these modules as part of a kernel image. Simply
  48 run the [`built-in.sh`](built-in.sh) script with the path to your kernel
  49 source directory as an argument.  It will symlink the lttng-modules directory
  50 in the kernel sources and add an include in the kernel Makefile.
  51
  52 Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.
  53
  54
  55 ### Required kernel config options
  56
  57 Make sure your target kernel has the following config options enabled:
  58
  59   - `CONFIG_MODULES`: loadable module support
  60   - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is
  61      necessary until the few required missing symbols are exported to GPL
  62      modules from mainline
  63   - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source
  64   - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation
  65      (enabled as a side-effect of any of the perf/ftrace/blktrace
  66      instrumentation features)
  67
  68
  69 ### Supported (optional) kernel config options
  70
  71 The following kernel configuration options will affect the features
  72 available from LTTng:
  73
  74   - `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing:
  75
  76         lttng enable-event -k --syscall
  77         lttng enable-event -k -a
  78
  79   - `CONFIG_PERF_EVENTS`: performance counters:
  80
  81         lttng add-context -t perf:*
  82
  83   - `CONFIG_EVENT_TRACING`: needed to allow block layer tracing
  84   - `CONFIG_KPROBES`: dynamic probes:
  85
  86         lttng enable-event -k --probe ...
  87
  88   - `CONFIG_KRETPROBES`: dynamic function entry/return probes:
  89
  90         lttng enable-event -k --function ...
  91
  92   - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
  93     number and name
  94
  95
  96 Usage
  97 -----
  98
  99 Use [LTTng-tools](https://lttng.org/download) to control the tracer.
 100 The session daemon of LTTng-tools should automatically load the LTTng
 101 kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
 102 to print traces as a human-readable text log.
 103
 104
 105 Support
 106 -------
 107
 108 Linux kernels >= 2.6.36 are supported.
 109
 110
 111 Notes
 112 -----
 113
 114 ### About perf PMU counters support
 115
 116 Each PMU counter has its zero value set when it is attached to a context with
 117 add-context. Therefore, it is normal that the same counters attached to both the
 118 stream context and event context show different values for a given event; what
 119 matters is that they increment at the same rate.