| 1 | --- |
| 2 | id: using-lttng |
| 3 | --- |
| 4 | |
| 5 | Using LTTng involves two main activities: **instrumenting** and |
| 6 | **controlling tracing**. |
| 7 | |
| 8 | _[Instrumenting](#doc-instrumenting)_ is the process of inserting probes |
| 9 | into some source code. It can be done manually, by writing tracepoint |
| 10 | calls at specific locations in the source code of the program to trace, |
| 11 | or more automatically using dynamic probes (address in assembled code, |
| 12 | symbol name, function entry/return, and others). |
| 13 | |
| 14 | It has to be noted that, as an LTTng user, you may not have to worry |
| 15 | about the instrumentation process. Indeed, you may want to trace a |
| 16 | program already instrumented. As an example, the Linux kernel is |
| 17 | thoroughly instrumented, which is why you can trace it without caring |
| 18 | about adding probes. |
| 19 | |
| 20 | _[Controlling tracing](#doc-controlling-tracing)_ is everything |
| 21 | that can be done by the LTTng session daemon, which is controlled using |
| 22 | `liblttng-ctl` or its command line utility, `lttng`: creating tracing |
| 23 | sessions, listing tracing sessions and events, enabling/disabling |
| 24 | events, starting/stopping the tracers, taking snapshots, amongst many |
| 25 | other commands. |
| 26 | |
| 27 | This chapter is a complete user guide of both activities, |
| 28 | with common use cases of LTTng exposed throughout the text. It is |
| 29 | assumed that you are familiar with LTTng's concepts (events, channels, |
| 30 | domains, tracing sessions) and that you understand the roles of its |
| 31 | components (daemons, libraries, command line tools); if not, we invite |
| 32 | you to read the [Understanding LTTng](#doc-understanding-lttng) chapter |
| 33 | before you begin reading this one. |
| 34 | |
| 35 | If you're new to LTTng, we suggest that you rather start with the |
| 36 | [Getting started](#doc-getting-started) small guide first, then come |
| 37 | back here to broaden your knowledge. |
| 38 | |
| 39 | If you're only interested in tracing the Linux kernel with its current |
| 40 | instrumentation, you may skip the |
| 41 | [Instrumenting](#doc-instrumenting) section. |