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://urcu.so/) >= 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
  30 The following items are _optional_ dependencies:
  31
  32   - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
  33     Enables the use of `lttng view` command.
  34     - Debian/Ubuntu package: `babeltrace`
  35   - **`libxml2` >= 2.7.6**:  XML document parsing library. Needed for
  36     tracing session configuration saving/loading and machine interface
  37     output support.
  38     - Debian/Ubuntu package: `libxml2-dev`
  39   - **Perl**: needed for `make check` and tests.
  40   - **Python >= 3.0**: needed for `make check` and tests.
  41     - Debian/Ubuntu package: `python3`
  42   - **SWIG >= 2.0** and **Python 3 development headers**: needed for
  43     Python bindings
  44     (enabled at configure time with the `--enable-python-bindings` option).
  45     - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
  46   - **modprobe**: needed for automatic LTTng kernel modules loading
  47     (kernel tracing).
  48   - **bash**: needed for running `make check`.
  49
  50
  51 Building
  52 --------
  53
  54 This source tree is based on the Autotools suite from GNU to simplify
  55 portability. Here are some things you should have on your system in
  56 order to compile the Git repository tree:
  57
  58   - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50,
  59     Autoheader >= 2.50; make sure your system-wide `automake` points to
  60     a recent version!)
  61   - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2
  62   - Flex >= 2.5.35
  63   - Bison >= 2.4
  64
  65 If you use GNU gold, which is _not_ mandatory, make sure you have this
  66 version:
  67
  68   - GNU gold >= 2.22
  69
  70 Before this version of GNU gold, we hit a
  71 [known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
  72 Be advised that with GNU gold, you might have to specify
  73 `-L/usr/local/lib` in `LDFLAGS`.
  74
  75 If you get the tree from the Git repository, you will need to run
  76
  77     ./bootstrap
  78
  79 in its root. It calls all the GNU tools needed to prepare the tree
  80 configuration.
  81
  82 To build LTTng-tools, do:
  83
  84     ./configure
  85     make
  86     sudo make install
  87     sudo ldconfig
  88
  89 If you want Python bindings, add the `--enable-python-bindings` option
  90 to `configure`. Please note that some distributions will need the
  91 following environment variables set before running configure:
  92
  93     export PYTHON="python3"
  94     export PYTHON_CONFIG="/usr/bin/python3-config"
  95
  96
  97 Using
  98 -----
  99
 100 Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
 101 with LTTng tracing. You can also use the `-h` or `--help` option of
 102 any `lttng` command, e.g.:
 103
 104     lttng enable-event --help
 105
 106 A network streaming HOWTO can be found in
 107 [`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
 108 helps you understand how to stream a LTTng 2.x trace.
 109
 110 A Python binding HOWTO can be found in
 111 [`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
 112 understand how to use the Python module to control LTTng.
 113
 114
 115 Contact
 116 -------
 117
 118 Maintainer: [David Goulet](mailto:dgoulet@efficios.com)
 119
 120 Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
 121
 122
 123 Package contents
 124 ----------------
 125
 126 This package contains the following elements:
 127
 128   - `doc`: LTTng-tools documentation.
 129   - `include`: the public header files that will be installed on the system.
 130   - `src/bin`: source code of LTTng-tools programs.
 131     - `lttng-consumerd`: consumer daemon.
 132     - `lttng-relayd`: relay daemon.
 133     - `lttng-sessiond`: session daemon.
 134     - `lttng`: command line interface for LTTng tracing control.
 135   - `src/common`: common LTTng-tools source code.
 136     - `compat`: compatibility library mostly for FreeBSD and Linux.
 137     - `config`: tracing session configuration saving/loading.
 138     - `hashtable`: library wrapper over Userspace RCU hashtables.
 139     - `health`: health check subsytem.
 140     - `index`: CTF index utilities.
 141     - `kernel-consumer`: Linux kernel consumer.
 142     - `kernel-ctl`: Linux kernel tracer control.
 143     - `relayd`: relay daemon control.
 144     - `sessiond-comm`: session daemon communication.
 145     - `ust-consumer`: user space consumer.
 146   - `src/lib`: source code of LTTng-tools libraries.
 147     - `lttng-ctl`: LTTng control library.
 148   - `tests`: various test programs.