4 _by [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)_
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.
13 Other notable features:
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).
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:
33 sudo make modules_install
36 The above commands will build LTTng-modules against your
37 current kernel. If you need to build LTTng-modules against a custom
40 make KERNELDIR=/path/to/custom/kernel
41 sudo make KERNELDIR=/path/to/custom/kernel modules_install
42 sudo depmod -a kernel_version
45 ### Kernel built-in support
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
53 Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.
56 ### Required kernel config options
58 Make sure your target kernel has the following config options enabled:
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.
72 ### Supported (optional) kernel config options
74 The following kernel configuration options will affect the features
77 - `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing:
79 lttng enable-event -k --syscall
80 lttng enable-event -k -a
82 - `CONFIG_PERF_EVENTS`: performance counters:
84 lttng add-context -t perf:*
86 - `CONFIG_EVENT_TRACING`: needed to allow block layer tracing
87 - `CONFIG_KPROBES`: dynamic probes:
89 lttng enable-event -k --probe ...
91 - `CONFIG_KRETPROBES`: dynamic function entry/return probes:
93 lttng enable-event -k --function ...
95 - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
98 ### LTTng specific kernel config options
100 The following kernel configuration options are provided by LTTng:
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:
106 make CONFIG_LTTNG_EXPERIMENTAL_BITWISE_ENUM=y
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
113 Customization/Extension
114 -----------------------
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
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.
139 Linux kernels >= 3.0 are supported. The stable-2.12 branch supports
140 Linux kernels < 5.18.
146 ### About perf PMU counters support
148 Each PMU counter has its zero value set when it is attached to a context with
149 add-context. Therefore, it is normal that the same counters attached to both the
150 stream context and event context show different values for a given event; what
151 matters is that they increment at the same rate.
157 The LTTng project supports the last two released stable versions
158 (e.g. stable-2.13 and stable-2.12).
160 Fixes are backported from the master branch to the last stable version
161 unless those fixes would break the ABI or API. Those fixes may be backported
162 to the second-last stable version, depending on complexity and ABI/API
165 Security fixes are backported from the master branch to both of the last stable
166 version and the the second-last stable version.
168 New kernel version enablement commits are integrated into the master branch and
169 backported to the last stable version.
171 New features are integrated into the master branch and not backported to the
177 You can contact the maintainers on the following mailing list:
178 `lttng-dev@lists.lttng.org`.
180 IRC channel: [#lttng](irc://irc.oftc.net/lttng) on the OFTC network
182 Bug tracker: [LTTng-modules bug tracker](https://bugs.lttng.org/projects/lttng-modules)
184 Code review: [_lttng-modules_ project](https://review.lttng.org/q/project:lttng-modules) on LTTng Review
186 Continuous integration: [LTTng-modules](https://ci.lttng.org/view/LTTng-modules/) on LTTng's CI
188 GitHub mirror: [lttng/lttng-modules](https://github.com/lttng/lttng-modules)
190 Patches are principally submitted and reviewed on [LTTng Review](https://review.lttng.org),
191 but may also be submitted to the [mailing list](mailto:lttng-dev@lists.lttng.org)
192 with the subject prefix `PATCH lttng-modules` or by pull request on the
193 [GitHub mirror](https://github.com/lttng/lttng-modules).