README.md

   1 LTTng&#8209;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&#8209;tools**_ is a set of components to control
   8 [LTTng](https://lttng.org/) tracing.
   9
  10 The project includes:
  11
  12 * The LTTng [session daemon](https://lttng.org/man/8/lttng-sessiond/).
  13 * The LTTng consumer daemon.
  14 * The LTTng [relay daemon](https://lttng.org/man/8/lttng-relayd/).
  15 * liblttng&#8209;ctl, a library with a C&nbsp;API used to communicate
  16   with the session daemon.
  17 * Python&nbsp;3 bindings of liblttng&#8209;ctl.
  18 * [`lttng`](https://lttng.org/man/1/lttng/),
  19   a command-line tool over liblttng&#8209;ctl.
  20 * [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line
  21   tool to recover and view LTTng&nbsp;2 trace buffers in the event of
  22   a crash.
  23
  24 Required and optional dependencies
  25 ----------------------------------
  26 You need the following dependencies to build and run the
  27 LTTng&#8209;tools components:
  28
  29 * **Linux kernel&nbsp;≥&nbsp;2.6.27**
  30
  31   Use `--disable-epoll` at [build configuration](#configure) time to
  32   build LTTng&#8209;tools for an older kernel. However, note that we
  33   can't provide any guarantee below 2.6.27.
  34
  35 * **[Userspace&nbsp;RCU](http://www.liburcu.org/) ≥ 0.9.0**.
  36
  37   Debian/Ubuntu package: `liburcu-dev`.
  38
  39 * **popt&nbsp;≥&nbsp;1.13**
  40
  41   Debian/Ubuntu package: `libpopt-dev`.
  42
  43 * **[Libxml2](http://xmlsoft.org/)&nbsp;≥&nbsp;2.7.6**
  44
  45   Debian/Ubuntu package: `libxml2-dev`
  46
  47 The following dependencies are optional:
  48
  49 * **[Babeltrace&nbsp;2](https://babeltrace.org/)**: default viewer
  50   of the [`lttng view`](https://lttng.org/man/1/lttng-view/)
  51   command.
  52
  53   Debian/Ubuntu package: `babeltrace2`
  54
  55 * **[LTTng&#8209;UST](https://lttng.org/)** (same minor version as
  56   LTTng&#8209;tools):
  57   LTTng user space tracing (applications and libraries).
  58
  59   Debian/Ubuntu package: `liblttng-ust-dev`
  60
  61 * **Perl**: `make check` and tests.
  62
  63 * **[Python](https://www.python.org/)&nbsp;≥&nbsp;3.0**:
  64   `make check` and tests.
  65
  66   Debian/Ubuntu package: `python3`
  67
  68 * **[SWIG](http://www.swig.org/)&nbsp;≥&nbsp;2.0** and
  69   **Python&nbsp;3 development headers**: Python bindings
  70   (enabled at [build configuration](#configure) time with the
  71   `--enable-python-bindings` option).
  72
  73   Debian/Ubuntu packages: `swig2.0` and `python3-dev`
  74
  75 * **modprobe** and/or
  76   **[kmod](https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/)&nbsp;≥&nbsp;22**:
  77   automatic LTTng kernel modules loading (kernel tracing).
  78
  79 * **Bash**: `make check`.
  80
  81 * **[`man`](http://man7.org/linux/man-pages/man1/man.1.html)**
  82   (manual pager): view `lttng` command manual
  83   pages with the `--help` option or with the
  84   [`lttng help`](https://lttng.org/man/1/lttng-help/) command.
  85
  86   Note that you can use the [build configuration](#configure) option
  87   `--enable-embedded-help` to embed the manual pages into the
  88   `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs
  89   so that you don't need `man` to view them.
  90
  91 * **[libpfm](http://perfmon2.sourceforge.net/)&nbsp;≥&nbsp;4.0**:
  92   perf regression test suite.
  93
  94   Debian/Ubuntu package: `libpfm4-dev`
  95
  96 LTTng&#8209;tools supports both the LTTng Linux kernel tracer and LTTng
  97 user space tracer sharing the same _minor_ version. While some minor
  98 releases do not change the tracer ABIs and _could_ work, no testing is
  99 performed to ensure that cross-version compatibility is maintained.
 100
 101 You don't need to rebuild or modify applications instrumented with older
 102 versions of the LTTng&#8209;UST project to make them work with the
 103 components of the latest LTTng&#8209;tools release.
 104
 105 See the [LTTng Documentation](https://lttng.org/docs/) for more
 106 information on versioning.
 107
 108 Build from source
 109 -----------------
 110 ### Dependencies
 111
 112 You need the following tools to build LTTng&#8209;tools:
 113
 114 * **[GNU&nbsp;Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)**
 115   (**Automake&nbsp;≥&nbsp;1.10**,
 116   **Autoconf&nbsp;≥&nbsp;2.64**, and **Autoheader&nbsp;≥&nbsp;2.50**)
 117
 118 * **[GNU&nbsp;Libtool](http://www.gnu.org/software/autoconf/)&nbsp;≥&nbsp;2.2**
 119
 120 * **[Flex](https://github.com/westes/flex/)&nbsp;≥&nbsp;2.5.35**
 121
 122 * **[Bison](https://www.gnu.org/software/bison/)&nbsp;≥&nbsp;2.4**
 123
 124 To build the LTTng&#8209;tools manual pages:
 125
 126 * **[AsciiDoc](https://www.methods.co.nz/asciidoc/)&nbsp;≥&nbsp;8.4.5**
 127
 128   Previous versions could work, but were not tested.
 129
 130 * **[xmlto](https://pagure.io/xmlto)&nbsp;≥&nbsp;0.0.21**
 131
 132   Previous versions could work, but were not tested.
 133
 134 If you use GNU&nbsp;gold, which is _not_ mandatory:
 135
 136 * **GNU&nbsp;gold&nbsp;≥&nbsp;2.22**
 137
 138 Note that with GNU&nbsp;gold, you might have to add
 139 `-L/usr/local/lib` to the `LDFLAGS` environment variable.
 140
 141 ### Build steps
 142
 143 1. **If you have the LTTng&#8209;tools Git source**, run:
 144
 145        $ ./bootstrap
 146
 147    This script creates the `configure` script.
 148
 149 2. <span id="configure"></span>Configure the build:
 150
 151        $ ./configure
 152
 153    If you want the liblttng&#8209;ctl Python bindings, use the
 154    `--enable-python-bindings` option. See also the
 155    `PYTHON` and `PYTHON_CONFIG` environment variables in
 156    `./configure --help`.
 157
 158    If you don't want to build the manual pages, use the
 159    `--disable-man-pages` option.
 160
 161    If you want to embed the manual pages into the
 162    `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs
 163    so that you don't need `man` to view them, use the
 164    `--enable-embedded-help` option.
 165
 166    If your Linux kernel is older than 2.6.27, use the
 167    `--enable-epoll` option.
 168
 169    This build configuration script finds LTTng&#8209;UST with
 170    [pkg&#8209;config](https://www.freedesktop.org/wiki/Software/pkg-config/):
 171    set the `PKG_CONFIG_PATH` environment variable accordingly if
 172    pkg&#8209;config cannot find the `lttng-ust` package information.
 173
 174    See `./configure --help` for the complete list of options.
 175
 176 3. Build the project:
 177
 178        $ make
 179
 180 4. Install the project:
 181
 182        $ sudo make install
 183        $ sudo ldconfig
 184
 185 Usage
 186 -----
 187 See the [Tracing control](https://lttng.org/docs/#doc-controlling-tracing)
 188 section of the LTTng Documentation to learn how to use the
 189 LTTng&#8209;tools components.
 190
 191 See also the [LTTng manual pages](https://lttng.org/man/) (all
 192 section&nbsp;1 and&nbsp;8 pages).
 193
 194 As there's no official liblttng&#8209;ctl Python bindings yet, see
 195 [`doc/python-howto.txt`](doc/python-howto.txt) to understand how to
 196 use them.
 197
 198 Community
 199 ---------
 200 * **Mailing list**:
 201   [lttng&#8209;dev](https://lists.lttng.org/cgi-bin/mailman/listinfo).
 202
 203 * **IRC channel**:
 204   [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network.
 205
 206 * **Bug tracker**::
 207   [LTTng&#8209;tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/).
 208
 209 * **GitHub project**:
 210   [lttng/lttng&#8209;tools](https://github.com/lttng/lttng-tools/).
 211
 212 * **Continuous integration**:
 213   [LTTng CI](https://ci.lttng.org/).
 214
 215 * **Code review**:
 216   [_lttng&#8209;tools_ project](https://review.lttng.org/q/project:lttng-tools)
 217   on LTTng Review.