| 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. |