| 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 >= 3.0 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. |