| 1 | --- |
| 2 | id: preface |
| 3 | --- |
| 4 | |
| 5 | <div class="copyright"> |
| 6 | <p> |
| 7 | Copyright © 2014 The LTTng Project |
| 8 | </p> |
| 9 | |
| 10 | <p> |
| 11 | This work is licensed under a |
| 12 | <a class="ext" href="http://creativecommons.org/licenses/by/4.0/">Creative |
| 13 | Commons Attribution 4.0 International License</a>. |
| 14 | </p> |
| 15 | </div> |
| 16 | |
| 17 | |
| 18 | ## Welcome! |
| 19 | |
| 20 | Welcome to the **LTTng Documentation**! |
| 21 | |
| 22 | The _Linux Trace Toolkit: next generation_ |
| 23 | is an open source system software package for correlated tracing of the |
| 24 | Linux kernel, user applications and libraries. LTTng consists of kernel |
| 25 | modules (for Linux kernel tracing) and dynamically loaded libraries (for |
| 26 | user application and library tracing). It is controlled by a session |
| 27 | daemon, which receives commands from a command line interface. |
| 28 | |
| 29 | |
| 30 | ### Convention |
| 31 | |
| 32 | Function and argument names, variable names, command names, |
| 33 | file system paths, file names and other precise strings are written |
| 34 | using a <code>monospaced typeface</code> in this document. An |
| 35 | <code><em>italic</em> word</code> within such a block is a |
| 36 | placeholder, usually described in the following sentence. |
| 37 | |
| 38 | Practical tips and sidenotes are given throughout the document using a |
| 39 | blue background: |
| 40 | |
| 41 | <div class="tip"> |
| 42 | <p><span class="t">Tip:</span>Make sure you read the tips.</p> |
| 43 | </div> |
| 44 | |
| 45 | Terminal boxes are used to show command lines: |
| 46 | |
| 47 | <pre class="term"> |
| 48 | echo This is a terminal box |
| 49 | </pre> |
| 50 | |
| 51 | Typical command prompts, like `$` and `#`, are not shown in terminal |
| 52 | boxes to make copy/paste operations easier, especially for multiline |
| 53 | commands which may be copied and pasted as is in a user's terminal. |
| 54 | Commands to be executed as a root user begin with `sudo`. |
| 55 | |
| 56 | |
| 57 | ### Target audience |
| 58 | |
| 59 | The material of this documentation is appropriate for intermediate to |
| 60 | advanced software developers working in a Linux environment who are |
| 61 | interested in efficient software tracing. LTTng may also be worth a |
| 62 | try for students interested in the inner mechanics of their systems. |
| 63 | |
| 64 | Readers who do not have a programming background may wish to skip |
| 65 | everything related to instrumentation, which requires, most of the |
| 66 | time, some programming language skills. |
| 67 | |
| 68 | <div class="tip"> |
| 69 | <p><span class="t">Note to readers:</span>This is an <strong>open |
| 70 | documentation</strong>: its source is available in a |
| 71 | <a class="ext" href="https://github.com/lttng/lttng-docs">public Git |
| 72 | repository</a>. Should you find any error in the contents of this text, |
| 73 | any grammatical mistake, or any dead link, we would be very grateful if |
| 74 | you would fill a GitHub issue for it or, even better, contribute a patch |
| 75 | to this documentation by creating a pull request.</p> |
| 76 | </div> |
| 77 | |
| 78 | ### Chapter descriptions |
| 79 | |
| 80 | What follows is a list of brief descriptions of this documentation's |
| 81 | chapters. The latter are ordered in such a way as to make the reading |
| 82 | as linear as possible. |
| 83 | |
| 84 | 1. [Nuts and bolts](#doc-nuts-and-bolts) explains the |
| 85 | rudiments of software tracing and the rationale behind the |
| 86 | LTTng project. |
| 87 | 2. [Installing LTTng](#doc-installing-lttng) is divided into |
| 88 | sections describing the steps needed to get a working installation |
| 89 | of LTTng packages for common Linux distributions and from its |
| 90 | source. |
| 91 | 3. [Getting started](#doc-getting-started) is a very concise guide to |
| 92 | get started quickly with LTTng kernel and user space tracing. This |
| 93 | chapter is recommended if you're new to LTTng or software tracing |
| 94 | in general. |
| 95 | 4. [Understanding LTTng](#doc-understanding-lttng) deals with some |
| 96 | core concepts and components of the LTTng suite. Understanding |
| 97 | those is important since the next chapter assumes you're familiar |
| 98 | with them. |
| 99 | 5. [Using LTTng](#doc-using-lttng) is a complete user guide of the |
| 100 | LTTng project. It shows in great details how to instrument user |
| 101 | applications and the Linux kernel, how to control tracing sessions |
| 102 | using the `lttng` command line tool and miscellaneous practical use |
| 103 | cases. |
| 104 | 6. [Reference](#doc-reference) contains references of LTTng components, |
| 105 | like links to online manpages and various APIs. |
| 106 | |
| 107 | We recommend that you read the above chapters in this order, although |
| 108 | some of them may be skipped depending on your situation. You may skip |
| 109 | [Nuts and bolts](#doc-nuts-and-bolts) if you're familiar with tracing |
| 110 | and LTTng. Also, you may jump over |
| 111 | [Installing LTTng](#doc-installing-lttng) if LTTng is already properly |
| 112 | installed on your target system. |
| 113 | |
| 114 | |
| 115 | ### Acknowledgements |
| 116 | |
| 117 | A few people made the online LTTng Documentation possible. |
| 118 | |
| 119 | Philippe Proulx wrote and formatted most of the text. |
| 120 | Daniel U. Thibault, from the |
| 121 | <abbr title="Defence Research and Development Canada">DRDC</abbr>, |
| 122 | wrote an open guide called <em>LTTng: The Linux Trace Toolkit Next |
| 123 | Generation — A Comprehensive User's Guide (version 2.3 |
| 124 | edition)</em> which was mostly used to complete parts of the |
| 125 | [Understanding LTTng](#doc-understanding-lttng) chapter and for a few |
| 126 | passages here and there. |
| 127 | The whole <a href="http://www.efficios.com/" class="ext">EfficiOS</a> |
| 128 | team (Christian Babeux, Antoine Busque, Julien Desfossez, |
| 129 | Mathieu Desnoyers, Jérémie Galarneau and David Goulet) made essential |
| 130 | reviews of the whole document. |
| 131 | |
| 132 | We sincerely thank everyone who helped make this documentation what |
| 133 | it is. We hope you enjoy reading it as much as we did writing it. |