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