| 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.9.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. |