README.md

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