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). |
ac2440f2 PP |
69 | |
70 | ||
71 | ### Supported (optional) kernel config options | |
72 | ||
73 | The following kernel configuration options will affect the features | |
74 | available from LTTng: | |
75 | ||
76 | - `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing: | |
77 | ||
78 | lttng enable-event -k --syscall | |
79 | lttng enable-event -k -a | |
80 | ||
81 | - `CONFIG_PERF_EVENTS`: performance counters: | |
82 | ||
83 | lttng add-context -t perf:* | |
84 | ||
85 | - `CONFIG_EVENT_TRACING`: needed to allow block layer tracing | |
86 | - `CONFIG_KPROBES`: dynamic probes: | |
87 | ||
88 | lttng enable-event -k --probe ... | |
89 | ||
90 | - `CONFIG_KRETPROBES`: dynamic function entry/return probes: | |
91 | ||
92 | lttng enable-event -k --function ... | |
93 | ||
94 | - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device | |
95 | number and name | |
96 | ||
47491cdf MD |
97 | Customization/Extension |
98 | ----------------------- | |
99 | ||
100 | The lttng-modules source includes definitions for the actual callback | |
101 | functions that will be attached to the kernel tracepoints by lttng. | |
102 | The lttng-modules project implements its own macros generating these | |
103 | callbacks: the LTTNG_TRACEPOINT_EVENT macro family found in | |
104 | instrumentation/events/lttng-module/. In order to show up in a | |
105 | lttng-modules trace, a kernel tracepoint must be defined within the | |
106 | kernel tree, and also defined within lttng-modules with the | |
107 | LTTNG_TRACEPOINT_EVENT macro family. Customizations or extensions must | |
108 | be done by modifying instances of these macros within the lttng-modules | |
109 | source. | |
ac2440f2 | 110 | |
f59ec0be | 111 | Usage |
ac2440f2 PP |
112 | ----- |
113 | ||
114 | Use [LTTng-tools](https://lttng.org/download) to control the tracer. | |
115 | The session daemon of LTTng-tools should automatically load the LTTng | |
116 | kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace) | |
117 | to print traces as a human-readable text log. | |
118 | ||
119 | ||
120 | Support | |
121 | ------- | |
122 | ||
88eafb70 | 123 | Linux kernels >= 3.0 are supported. |
ac2440f2 PP |
124 | |
125 | ||
126 | Notes | |
127 | ----- | |
128 | ||
129 | ### About perf PMU counters support | |
130 | ||
131 | Each PMU counter has its zero value set when it is attached to a context with | |
132 | add-context. Therefore, it is normal that the same counters attached to both the | |
133 | stream context and event context show different values for a given event; what | |
134 | matters is that they increment at the same rate. |