| 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 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‑ctl, a library with a C API used to communicate |
| 16 | with the session daemon. |
| 17 | * Python 3 bindings of liblttng‑ctl. |
| 18 | * [`lttng`](https://lttng.org/man/1/lttng/), |
| 19 | a command-line tool over liblttng‑ctl. |
| 20 | * [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line |
| 21 | tool to recover and view LTTng 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‑tools components: |
| 28 | |
| 29 | * **Linux kernel ≥ 2.6.27** |
| 30 | |
| 31 | Use `--disable-epoll` at [build configuration](#configure) time to |
| 32 | build LTTng‑tools for an older kernel. However, note that we |
| 33 | can't provide any guarantee below 2.6.27. |
| 34 | |
| 35 | * **[Userspace RCU](http://www.liburcu.org/) ≥ 0.9.0**. |
| 36 | |
| 37 | Debian/Ubuntu package: `liburcu-dev`. |
| 38 | |
| 39 | * **popt ≥ 1.13** |
| 40 | |
| 41 | Debian/Ubuntu package: `libpopt-dev`. |
| 42 | |
| 43 | * **[Libxml2](http://xmlsoft.org/) ≥ 2.7.6** |
| 44 | |
| 45 | Debian/Ubuntu package: `libxml2-dev` |
| 46 | |
| 47 | The following dependencies are optional: |
| 48 | |
| 49 | * **[Babeltrace 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‑UST](https://lttng.org/)** (same minor version as |
| 56 | LTTng‑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/) ≥ 3.0**: |
| 64 | `make check` and tests. |
| 65 | |
| 66 | Debian/Ubuntu package: `python3` |
| 67 | |
| 68 | * **[SWIG](http://www.swig.org/) ≥ 2.0** and |
| 69 | **Python 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/) ≥ 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/) ≥ 4.0**: |
| 92 | perf regression test suite. |
| 93 | |
| 94 | Debian/Ubuntu package: `libpfm4-dev` |
| 95 | |
| 96 | LTTng‑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‑UST project to make them work with the |
| 103 | components of the latest LTTng‑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‑tools: |
| 113 | |
| 114 | * **[GNU Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)** |
| 115 | (**Automake ≥ 1.10**, |
| 116 | **Autoconf ≥ 2.64**, and **Autoheader ≥ 2.50**) |
| 117 | |
| 118 | * **[GNU Libtool](http://www.gnu.org/software/autoconf/) ≥ 2.2** |
| 119 | |
| 120 | * **[Flex](https://github.com/westes/flex/) ≥ 2.5.35** |
| 121 | |
| 122 | * **[Bison](https://www.gnu.org/software/bison/) ≥ 2.4** |
| 123 | |
| 124 | To build the LTTng‑tools manual pages: |
| 125 | |
| 126 | * **[AsciiDoc](https://www.methods.co.nz/asciidoc/) ≥ 8.4.5** |
| 127 | |
| 128 | Previous versions could work, but were not tested. |
| 129 | |
| 130 | * **[xmlto](https://pagure.io/xmlto) ≥ 0.0.21** |
| 131 | |
| 132 | Previous versions could work, but were not tested. |
| 133 | |
| 134 | If you use GNU gold, which is _not_ mandatory: |
| 135 | |
| 136 | * **GNU gold ≥ 2.22** |
| 137 | |
| 138 | Note that with GNU 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‑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‑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‑UST with |
| 170 | [pkg‑config](https://www.freedesktop.org/wiki/Software/pkg-config/): |
| 171 | set the `PKG_CONFIG_PATH` environment variable accordingly if |
| 172 | pkg‑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‑tools components. |
| 190 | |
| 191 | See also the [LTTng manual pages](https://lttng.org/man/) (all |
| 192 | section 1 and 8 pages). |
| 193 | |
| 194 | As there's no official liblttng‑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‑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‑tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/). |
| 208 | |
| 209 | * **GitHub project**: |
| 210 | [lttng/lttng‑tools](https://github.com/lttng/lttng-tools/). |
| 211 | |
| 212 | * **Continuous integration**: |
| 213 | [LTTng CI](https://ci.lttng.org/). |
| 214 | |
| 215 | * **Code review**: |
| 216 | [_lttng‑tools_ project](https://review.lttng.org/q/project:lttng-tools) |
| 217 | on LTTng Review. |