Drop support for kernels < 4.4 from scsi instrumentation
[lttng-modules.git] / README.md
CommitLineData
ac2440f2
PP
1LTTng-modules
2=============
3
4_by [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)_
5
6
7LTTng kernel modules are Linux kernel modules which make
8[LTTng](http://lttng.org/) kernel tracing possible. They include
9essential control modules and many probes which instrument numerous
10interesting parts of Linux. LTTng-modules builds against a vanilla or
11distribution kernel, with no need for additional patches.
12
13Other 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
26Building
27--------
28
29To build and install LTTng-modules, you will need to have your kernel
30headers available (or access to your full kernel source tree), and do:
31
32 make
33 sudo make modules_install
34 sudo depmod -a
35
36The above commands will build LTTng-modules against your
37current kernel. If you need to build LTTng-modules against a custom
38kernel, 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
47It is also possible to build these modules as part of a kernel image. Simply
6c27a5cc
MJ
48run the [`scripts/built-in.sh`](scripts/built-in.sh) script with the path to
49your kernel source directory as an argument. It will symlink the
50lttng-modules directory in the kernel sources and add an include in the kernel
51Makefile.
f59ec0be
MJ
52
53Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.
54
55
ac2440f2
PP
56### Required kernel config options
57
58Make 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
74The following kernel configuration options will affect the features
75available 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
100The 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
113Customization/Extension
114-----------------------
115
116The lttng-modules source includes definitions for the actual callback
117functions that will be attached to the kernel tracepoints by lttng.
118The lttng-modules project implements its own macros generating these
119callbacks: the LTTNG_TRACEPOINT_EVENT macro family found in
120instrumentation/events/lttng-module/. In order to show up in a
121lttng-modules trace, a kernel tracepoint must be defined within the
122kernel tree, and also defined within lttng-modules with the
123LTTNG_TRACEPOINT_EVENT macro family. Customizations or extensions must
124be done by modifying instances of these macros within the lttng-modules
125source.
ac2440f2 126
f59ec0be 127Usage
ac2440f2
PP
128-----
129
130Use [LTTng-tools](https://lttng.org/download) to control the tracer.
131The session daemon of LTTng-tools should automatically load the LTTng
132kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
133to print traces as a human-readable text log.
134
135
136Support
137-------
138
c0f4130d 139Linux kernels >= 4.4 are supported.
ac2440f2
PP
140
141
142Notes
143-----
144
145### About perf PMU counters support
146
147Each PMU counter has its zero value set when it is attached to a context with
148add-context. Therefore, it is normal that the same counters attached to both the
149stream context and event context show different values for a given event; what
150matters is that they increment at the same rate.
This page took 0.053988 seconds and 4 git commands to generate.