contents/preface.md

   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&nbsp;&mdash;&nbsp;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.