| 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 or, put in other words, record its |
| 19 | history of 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. |