Fix: update vmscan instrumentation for v4.16
[lttng-modules.git] / README.md
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 [`built-in.sh`](built-in.sh) script with the path to your kernel
49 source directory as an argument. It will symlink the lttng-modules directory
50 in the kernel sources and add an include in the kernel Makefile.
51
52 Then configure your kernel as usual and enable the `CONFIG_LTTNG` option.
53
54
55 ### Required kernel config options
56
57 Make sure your target kernel has the following config options enabled:
58
59 - `CONFIG_MODULES`: loadable module support (not strictly required
60 when built into the kernel)
61 - `CONFIG_KALLSYMS`: see files in [`wrapper`](wrapper); this is
62 necessary until the few required missing symbols are exported to GPL
63 modules from mainline
64 - `CONFIG_HIGH_RES_TIMERS`: needed for LTTng 2.x clock source
65 - `CONFIG_TRACEPOINTS`: kernel tracepoint instrumentation
66 (enabled as a side-effect of any of the perf/ftrace/blktrace
67 instrumentation features)
68
69
70 ### Supported (optional) kernel config options
71
72 The following kernel configuration options will affect the features
73 available from LTTng:
74
75 - `CONFIG_HAVE_SYSCALL_TRACEPOINTS`: system call tracing:
76
77 lttng enable-event -k --syscall
78 lttng enable-event -k -a
79
80 - `CONFIG_PERF_EVENTS`: performance counters:
81
82 lttng add-context -t perf:*
83
84 - `CONFIG_EVENT_TRACING`: needed to allow block layer tracing
85 - `CONFIG_KPROBES`: dynamic probes:
86
87 lttng enable-event -k --probe ...
88
89 - `CONFIG_KRETPROBES`: dynamic function entry/return probes:
90
91 lttng enable-event -k --function ...
92
93 - `CONFIG_KALLSYMS_ALL`: state dump of mapping between block device
94 number and name
95
96
97 Usage
98 -----
99
100 Use [LTTng-tools](https://lttng.org/download) to control the tracer.
101 The session daemon of LTTng-tools should automatically load the LTTng
102 kernel modules when needed. Use [Babeltrace](https://lttng.org/babeltrace)
103 to print traces as a human-readable text log.
104
105
106 Support
107 -------
108
109 Linux kernels >= 2.6.36 are supported.
110
111
112 Notes
113 -----
114
115 ### About perf PMU counters support
116
117 Each PMU counter has its zero value set when it is attached to a context with
118 add-context. Therefore, it is normal that the same counters attached to both the
119 stream context and event context show different values for a given event; what
120 matters is that they increment at the same rate.
This page took 0.035527 seconds and 4 git commands to generate.