Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
1 | --- |
2 | id: instrumenting-linux-kernel | |
3 | --- | |
4 | ||
5 | The Linux kernel can be instrumented for LTTng tracing, either its core | |
6 | source code or a kernel module. It has to be noted that Linux is | |
7 | readily traceable using LTTng since many parts of its source code are | |
8 | already instrumented: this is the job of the upstream | |
9 | <a href="http://git.lttng.org/?p=lttng-modules.git" class="ext">LTTng-modules</a> | |
10 | package. This section presents how to add LTTng instrumentation where it | |
11 | does not currently exist and how to instrument custom kernel modules. | |
12 | ||
13 | All LTTng instrumentation in the Linux kernel is based on an existing | |
14 | infrastructure which bears the name of its main macro, `TRACE_EVENT()`. | |
15 | This macro is used to define tracepoints, | |
16 | each tracepoint having a name, usually with the | |
17 | <code><em>subsys</em>_<em>name</em></code> format, | |
18 | <code><em>subsys</em></code> being the subsystem name and | |
19 | <code><em>name</em></code> the specific event name. | |
20 | ||
21 | Tracepoints defined with `TRACE_EVENT()` may be inserted anywhere in | |
22 | the Linux kernel source code, after what callbacks, called _probes_, | |
23 | may be registered to execute some action when a tracepoint is | |
24 | executed. This mechanism is directly used by ftrace and perf, | |
25 | but cannot be used as is by LTTng: an adaptation layer is added to | |
26 | satisfy LTTng's specific needs. | |
27 | ||
28 | With that in mind, this documentation does not cover the `TRACE_EVENT()` | |
29 | format and how to use it, but it is mandatory to understand it and use | |
30 | it to instrument Linux for LTTng. A series of | |
31 | <abbr title="Linux Weekly News">LWN</abbr> articles explain | |
32 | `TRACE_EVENT()` in details: | |
33 | <a href="http://lwn.net/Articles/379903/" class="ext">part 1</a>, | |
34 | <a href="http://lwn.net/Articles/381064/" class="ext">part 2</a>, and | |
35 | <a href="http://lwn.net/Articles/383362/" class="ext">part 3</a>. | |
36 | Once you master `TRACE_EVENT()` enough for your use case, continue | |
37 | reading this section so that you can add the LTTng adaptation layer of | |
38 | instrumentation. | |
39 | ||
40 | This section first discusses the general method of instrumenting the | |
41 | Linux kernel for LTTng. This method is then reused for the specific | |
42 | case of instrumenting a kernel module. |