README.md

   1 LTTng-tools
   2 ===========
   3
   4 LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
   5 tracing. The project includes the LTTng session daemon, consumer damon
   6 and relay daemon, as well as `liblttng-ctl`, a C library used to
   7 communicate with the session daemon, and `lttng`, a command line
   8 interface to `liblttng-ctl`.
   9
  10
  11 Requirements and optional dependencies
  12 --------------------------------------
  13
  14 The following items are _required_ to build and run LTTng-tools
  15 components:
  16
  17   - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this
  18     version is needed. However, `poll()` is also supported by
  19     configuring LTTng-tools with the `--disable-epoll` option. Using
  20     that, the kernel version may probably be older, but we can't provide
  21     any guarantee. Please let us know if you are able to go lower
  22     without any problems.
  23   - **[`liburcu`](http://www.liburcu.org/) >= 0.8.0**: userspace RCU library,
  24     by Mathieu Desnoyers and Paul E. McKenney.
  25   - **`libpopt` >= 1.13**:  command line arguments parsing library.
  26     - Debian/Ubuntu package: `libpopt-dev`
  27   - **`libuuid`**: universally unique ID library
  28     - Debian/Ubuntu package: `uuid-dev`
  29   - **`libxml2` >= 2.7.6**:  XML document parsing library. Needed for
  30     tracing session configuration saving/loading and machine interface
  31     output support.
  32     - Debian/Ubuntu package: `libxml2-dev`
  33
  34
  35 The following items are _optional_ dependencies:
  36
  37   - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
  38     Enables the use of `lttng view` command.
  39     - Debian/Ubuntu package: `babeltrace`
  40   - **[LTTng UST](https://lttng.org) (same minor version as LTTng Tools)**:
  41     userspace tracer. Enables the tracing of userspace applications.
  42     - Debian/Ubuntu package: `liblttng-ust-dev`
  43   - **Perl**: needed for `make check` and tests.
  44   - **Python >= 3.0**: needed for `make check` and tests.
  45     - Debian/Ubuntu package: `python3`
  46   - **SWIG >= 2.0** and **Python 3 development headers**: needed for
  47     Python bindings
  48     (enabled at configure time with the `--enable-python-bindings` option).
  49     - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
  50   - **modprobe**: needed for automatic LTTng kernel modules loading
  51     (kernel tracing).
  52   - **bash**: needed for running `make check`.
  53
  54 LTTng-tools supports both the [LTTng Linux Kernel tracer](https://lttng.org)
  55 and [LTTng user space tracer](https://lttng.org) released as part of the same
  56 **minor** release series. While some releases do not change the tracer ABIs and
  57 should work with, no testing is performed to ensure cross-version compatibility
  58 is maintained.
  59
  60 Note that applications instrumented with older versions of the LTTng UST project
  61 do not have to be rebuilt or modified to work with the latest LTTng-tools.
  62 For more information on versioning, please refer to the
  63 [LTTng documentation](https://lttng.org/docs).
  64
  65 Building
  66 --------
  67
  68 This source tree is based on the Autotools suite from GNU to simplify
  69 portability. Here are some things you should have on your system in
  70 order to compile the Git repository tree:
  71
  72   - **GNU Autotools** (**Automake >= 1.10**, **Autoconf >= 2.64**,
  73     **Autoheader >= 2.50**; make sure your system-wide `automake` points
  74     to a recent version!)
  75   - **[GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2**
  76   - **Flex >= 2.5.35**
  77   - **Bison >= 2.4**
  78
  79 Optional packages to build LTTng-tools man pages:
  80
  81   - **AsciiDoc >= 8.4.5** (previous versions may work, but were
  82     not tested)
  83   - **xmlto >= 0.0.21** (previous versions may work, but were
  84     not tested)
  85
  86 If you use GNU gold, which is _not_ mandatory, make sure you have this
  87 version:
  88
  89   - **GNU gold >= 2.22**
  90
  91 Before this version of GNU gold, we hit a
  92 [known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
  93 Be advised that with GNU gold, you might have to specify
  94 `-L/usr/local/lib` in `LDFLAGS`.
  95
  96 If you get the tree from the Git repository, you will need to run
  97
  98     ./bootstrap
  99
 100 in its root. It calls all the GNU tools needed to prepare the tree
 101 configuration.
 102
 103 To build LTTng-tools, do:
 104
 105     ./configure
 106     make
 107     sudo make install
 108     sudo ldconfig
 109
 110 If you want Python bindings, add the `--enable-python-bindings` option
 111 to `configure`. Please note that some distributions will need the
 112 following environment variables set before running configure:
 113
 114     export PYTHON="python3"
 115     export PYTHON_CONFIG="/usr/bin/python3-config"
 116
 117
 118 Using
 119 -----
 120
 121 Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
 122 with LTTng tracing. You can also use the `-h` or `--help` option of
 123 any `lttng` command, e.g.:
 124
 125     lttng enable-event --help
 126
 127 A network streaming HOWTO can be found in
 128 [`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
 129 helps you understand how to stream a LTTng 2.x trace.
 130
 131 A Python binding HOWTO can be found in
 132 [`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
 133 understand how to use the Python module to control LTTng.
 134
 135
 136 Contact
 137 -------
 138
 139 Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
 140
 141 Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
 142
 143
 144 Package contents
 145 ----------------
 146
 147 This package contains the following elements:
 148
 149   - `doc`: LTTng-tools documentation.
 150   - `include`: the public header files that will be installed on the system.
 151   - `src/bin`: source code of LTTng-tools programs.
 152     - `lttng-consumerd`: consumer daemon.
 153     - `lttng-relayd`: relay daemon.
 154     - `lttng-sessiond`: session daemon.
 155     - `lttng`: command line interface for LTTng tracing control.
 156   - `src/common`: common LTTng-tools source code.
 157     - `compat`: compatibility library mostly for FreeBSD and Linux.
 158     - `config`: tracing session configuration saving/loading.
 159     - `hashtable`: library wrapper over Userspace RCU hashtables.
 160     - `health`: health check subsytem.
 161     - `index`: CTF index utilities.
 162     - `kernel-consumer`: Linux kernel consumer.
 163     - `kernel-ctl`: Linux kernel tracer control.
 164     - `relayd`: relay daemon control.
 165     - `sessiond-comm`: session daemon communication.
 166     - `ust-consumer`: user space consumer.
 167   - `src/lib`: source code of LTTng-tools libraries.
 168     - `lttng-ctl`: LTTng control library.
 169   - `tests`: various test programs.