contents/using-lttng/instrumenting/intro.md

   1 ---
   2 id: instrumenting
   3 ---
   4
   5 There are many examples of tracing and monitoring in our everyday life.
   6 You have access to real-time and historical weather reports and forecasts
   7 thanks to weather stations installed around the country. You know your
   8 possibly hospitalized friends' and family's hearts are safe thanks to
   9 electrocardiography. You make sure not to drive your car too fast
  10 and have enough fuel to reach your destination thanks to gauges visible
  11 on your dashboard.
  12
  13 All the previous examples have something in common: they rely on
  14 **probes**. Without electrodes attached to the surface of a body's
  15 skin, cardiac monitoring would be futile.
  16
  17 LTTng, as a tracer, is no different from the real life examples above.
  18 If you're about to trace a software system, i.e. record its history of
  19 execution, you better have probes in the subject you're
  20 tracing: the actual software. Various ways were developed to do this.
  21 The most straightforward one is to manually place probes, called
  22 _tracepoints_, in the software's source code. The Linux kernel tracing
  23 domain also allows probes added dynamically.
  24
  25 If you're only interested in tracing the Linux kernel, it may very well
  26 be that your tracing needs are already appropriately covered by LTTng's
  27 built-in Linux kernel tracepoints and other probes. Or you may be in
  28 possession of a user space application which has already been
  29 instrumented. In such cases, the work resides entirely in the design
  30 and execution of tracing sessions, allowing you to jump to
  31 [Controlling tracing](#doc-controlling-tracing) right now.
  32
  33 This section focuses on the following use cases of instrumentation:
  34
  35   * [C](#doc-c-application) and [C++](#doc-cxx-application) applications
  36   * [prebuilt user space tracing helpers](#doc-prebuilt-ust-helpers)
  37   * [Java application](#doc-java-application)
  38   * [Linux kernel](#doc-instrumenting-linux-kernel) module or the
  39     kernel itself
  40   * the [`/proc/lttng-logger` <abbr title="Application Binary Interface">ABI</abbr>](#doc-proc-lttng-logger-abi)
  41
  42 Some [advanced techniques](#doc-advanced-instrumenting-techniques) are
  43 also presented at the very end.