contents/using-lttng/instrumenting/instrumenting-linux-kernel/intro.md

   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.