projects / lttng-docs.git / blame
| 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. |