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