contents/preface.md

   1 ---
   2 id: preface
   3 ---
   4
   5 <div class="copyright">
   6     <p>
   7         Copyright © 2014-2015 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 to 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
 106 We recommend that you read the above chapters in this order, although
 107 some of them may be skipped depending on your situation. You may skip
 108 [Nuts and bolts](#doc-nuts-and-bolts) if you're familiar with tracing
 109 and the LTTng project. Also, you may jump over
 110 [Installing LTTng](#doc-installing-lttng) if LTTng is already properly
 111 installed on your target system.
 112
 113
 114 ### Acknowledgements
 115
 116 A few people made the online LTTng Documentation possible.
 117
 118 Philippe Proulx wrote and formatted most of the text.
 119 Daniel U. Thibault, from the
 120 <abbr title="Defence Research and Development Canada">DRDC</abbr>,
 121 wrote an open guide called <em>LTTng: The Linux Trace Toolkit Next
 122 Generation&nbsp;&mdash;&nbsp;A Comprehensive User's Guide (version 2.3
 123 edition)</em> which was mostly used to complete parts of the
 124 [Understanding LTTng](#doc-understanding-lttng) chapter and for a few
 125 passages here and there.
 126 The whole <a href="http://www.efficios.com/" class="ext">EfficiOS</a>
 127 team (Christian Babeux, Antoine Busque, Julien Desfossez,
 128 Mathieu Desnoyers, Jérémie Galarneau and David Goulet) made essential
 129 reviews of the whole document.
 130
 131 We sincerely thank everyone who helped make this documentation what
 132 it is. We hope you enjoy reading it as much as we did writing it.