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 [`scripts/built-in.sh`](scripts/built-in.sh) script with the path to
  49 your kernel source directory as an argument.  It will symlink the
  50 lttng-modules directory in the kernel sources and add an include in the kernel
  51 Makefile.
  52
  53 Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.
  54
  55
  56 ### Required kernel config options
  57
  58 Make sure your target kernel has the following config options enabled:
  59
  60   - `CONFIG_MODULES`: loadable module support (not strictly required
  61      when built into the kernel),
  62   - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is
  63      necessary until the few required missing symbols are exported to GPL
  64      modules from mainline,
  65   - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source,
  66   - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation
  67      (enabled as a side-effect of any of the perf/ftrace/blktrace
  68      instrumentation features).
  69   - `CONFIG_KPROBES` (5.7+): use kallsyms for kernel 5.7 and newer.
  70
  71
  72 ### Supported (optional) kernel config options
  73
  74 The following kernel configuration options will affect the features
  75 available from LTTng:
  76
  77   - `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing:
  78
  79         lttng enable-event -k --syscall
  80         lttng enable-event -k -a
  81
  82   - `CONFIG_PERF_EVENTS`: performance counters:
  83
  84         lttng add-context -t perf:*
  85
  86   - `CONFIG_EVENT_TRACING`: needed to allow block layer tracing
  87   - `CONFIG_KPROBES`: dynamic probes:
  88
  89         lttng enable-event -k --probe ...
  90
  91   - `CONFIG_KRETPROBES`: dynamic function entry/return probes:
  92
  93         lttng enable-event -k --function ...
  94
  95   - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
  96     number and name
  97
  98 ### LTTng specific kernel config options
  99
 100 The following kernel configuration options are provided by LTTng:
 101
 102   - `CONFIG_LTTNG`: Build LTTng (Defaults to 'm').
 103   - `CONFIG_LTTNG_EXPERIMENTAL_BITWISE_ENUM`: Enable the experimental bitwise
 104     enumerations (Defaults to 'n'). This can be enabled by building with:
 105
 106          make CONFIG_LTTNG_EXPERIMENTAL_BITWISE_ENUM=y
 107
 108   - `CONFIG_LTTNG_CLOCK_PLUGIN_TEST`: Build the test clock plugin (Defaults to
 109     'm'). This plugin overrides the trace clock and should always be built as a
 110     module for testing.
 111
 112
 113 Customization/Extension
 114 -----------------------
 115
 116 The lttng-modules source includes definitions for the actual callback
 117 functions that will be attached to the kernel tracepoints by lttng.
 118 The lttng-modules project implements its own macros generating these
 119 callbacks: the LTTNG_TRACEPOINT_EVENT macro family found in
 120 instrumentation/events/lttng-module/. In order to show up in a
 121 lttng-modules trace, a kernel tracepoint must be defined within the
 122 kernel tree, and also defined within lttng-modules with the
 123 LTTNG_TRACEPOINT_EVENT macro family. Customizations or extensions must
 124 be done by modifying instances of these macros within the lttng-modules
 125 source.
 126
 127 Usage
 128 -----
 129
 130 Use [LTTng-tools](https://lttng.org/download) to control the tracer.
 131 The session daemon of LTTng-tools should automatically load the LTTng
 132 kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
 133 to print traces as a human-readable text log.
 134
 135
 136 Support
 137 -------
 138
 139 Linux kernels >= 4.4 are supported.
 140
 141
 142 Notes
 143 -----
 144
 145 ### About perf PMU counters support
 146
 147 Each PMU counter has its zero value set when it is attached to a context with
 148 add-context. Therefore, it is normal that the same counters attached to both the
 149 stream context and event context show different values for a given event; what
 150 matters is that they increment at the same rate.
 151
 152
 153 Supported versions
 154 ------------------
 155
 156 The LTTng project supports the last two released stable versions
 157 (e.g. stable-2.13 and stable-2.12).
 158
 159 Fixes are backported from the master branch to the last stable version
 160 unless those fixes would break the ABI or API. Those fixes may be backported
 161 to the second-last stable version, depending on complexity and ABI/API
 162 compatibility.
 163
 164 Security fixes are backported from the master branch to both of the last stable
 165 version and the the second-last stable version.
 166
 167 New kernel version enablement commits are integrated into the master branch and
 168 backported to the last stable version.
 169
 170 New features are integrated into the master branch and not backported to the
 171 last stable branch.
 172
 173 Contacts
 174 --------
 175
 176 You can contact the maintainers on the following mailing list:
 177 `lttng-dev@lists.lttng.org`.
 178
 179 IRC channel: [#lttng](irc://irc.oftc.net/lttng) on the OFTC network
 180
 181 Bug tracker: [LTTng-modules bug tracker](https://bugs.lttng.org/projects/lttng-modules)
 182
 183 Code review: [_lttng-modules_ project](https://review.lttng.org/q/project:lttng-modules) on LTTng Review
 184
 185 Continuous integration: [LTTng-modules](https://ci.lttng.org/view/LTTng-modules/) on LTTng's CI
 186
 187 GitHub mirror: [lttng/lttng-modules](https://github.com/lttng/lttng-modules)
 188
 189 Patches are principally submitted and reviewed on [LTTng Review](https://review.lttng.org),
 190 but may also be submitted to the [mailing list](mailto:lttng-dev@lists.lttng.org)
 191 with the subject prefix `PATCH lttng-modules` or by pull request on the
 192 [GitHub mirror](https://github.com/lttng/lttng-modules).