Commit | Line | Data |
---|---|---|
5e0cbfb0 PP |
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 | ||
5e0cbfb0 PP |
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 C 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 using a GitHub 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. |