Commit | Line | Data |
---|---|---|
ac2440f2 PP |
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) | |
6bb4326c | 16 | (Common Trace Format) natively, |
ac2440f2 | 17 | - Tracepoints, function tracer, CPU Performance Monitoring Unit (PMU) |
6bb4326c | 18 | counters, kprobes, and kretprobes support, |
ac2440f2 PP |
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 | ||
f59ec0be MJ |
45 | ### Kernel built-in support |
46 | ||
47 | It is also possible to build these modules as part of a kernel image. Simply | |
6c27a5cc MJ |
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. | |
f59ec0be MJ |
52 | |
53 | Then configure your kernel as usual and enable the `CONFIG_LTTNG` option. | |
54 | ||
55 | ||
ac2440f2 PP |
56 | ### Required kernel config options |
57 | ||
58 | Make sure your target kernel has the following config options enabled: | |
59 | ||
66a86e0b | 60 | - `CONFIG_MODULES`: loadable module support (not strictly required |
6bb4326c | 61 | when built into the kernel), |
ac2440f2 PP |
62 | - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is |
63 | necessary until the few required missing symbols are exported to GPL | |
6bb4326c MD |
64 | modules from mainline, |
65 | - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source, | |
ac2440f2 PP |
66 | - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation |
67 | (enabled as a side-effect of any of the perf/ftrace/blktrace | |
6bb4326c | 68 | instrumentation features). |
a6576540 | 69 | - `CONFIG_KPROBES` (5.7+): use kallsyms for kernel 5.7 and newer. |
ac2440f2 PP |
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 | ||
c1551e57 MJ |
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 | ||
47491cdf MD |
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. | |
ac2440f2 | 126 | |
f59ec0be | 127 | Usage |
ac2440f2 PP |
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 | ||
c0f4130d | 139 | Linux kernels >= 4.4 are supported. |
ac2440f2 PP |
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. |