Fix: use lttng_waiter instead of futex in notification thread
[lttng-tools.git] / README.md
CommitLineData
adf4e918
PP
1LTTng-tools
2===========
3
83d28ca6
PP
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
adf4e918 7LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
6345ade6 8tracing. The project includes the LTTng session daemon, consumer daemon
adf4e918
PP
9and relay daemon, as well as `liblttng-ctl`, a C library used to
10communicate with the session daemon, and `lttng`, a command line
11interface to `liblttng-ctl`.
12
13
14Requirements and optional dependencies
15--------------------------------------
16
17The following items are _required_ to build and run LTTng-tools
18components:
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.
99ad3285 26 - **[`liburcu`](http://www.liburcu.org/) >= 0.8.0**: userspace RCU library,
adf4e918
PP
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`
2199563c
JG
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
adf4e918
PP
37
38The 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`
4c780623
JG
43 - **[LTTng UST](https://lttng.org) (same minor version as LTTng Tools)**:
44 userspace tracer. Enables the tracing of userspace applications.
213ff7c7 45 - Debian/Ubuntu package: `liblttng-ust-dev`
adf4e918
PP
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).
1bdcd9d8 55 - **bash**: needed to run `make check`.
d1bec732
PP
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.
6faa26ca
JD
60 - **libpfm >= 4.0**: needed to run the perf regression test suite.
61 - Debian/Ubuntu package: `libpfm4-dev`
adf4e918 62
4c780623
JG
63LTTng-tools supports both the [LTTng Linux Kernel tracer](https://lttng.org)
64and [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
66should work with, no testing is performed to ensure cross-version compatibility
67is maintained.
68
69Note that applications instrumented with older versions of the LTTng UST project
70do not have to be rebuilt or modified to work with the latest LTTng-tools.
71For more information on versioning, please refer to the
72[LTTng documentation](https://lttng.org/docs).
adf4e918
PP
73
74Building
75--------
76
77This source tree is based on the Autotools suite from GNU to simplify
78portability. Here are some things you should have on your system in
79order to compile the Git repository tree:
80
1b1af97e
PP
81 - **GNU Autotools** (**Automake >= 1.10**, **Autoconf >= 2.64**,
82 **Autoheader >= 2.50**; make sure your system-wide `automake` points
46863ff0 83 to a recent version)
1b1af97e
PP
84 - **[GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2**
85 - **Flex >= 2.5.35**
86 - **Bison >= 2.4**
adf4e918 87
8558f6a2
PP
88Optional 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
adf4e918
PP
95If you use GNU gold, which is _not_ mandatory, make sure you have this
96version:
97
1b1af97e 98 - **GNU gold >= 2.22**
adf4e918
PP
99
100Before this version of GNU gold, we hit a
101[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
102Be advised that with GNU gold, you might have to specify
103`-L/usr/local/lib` in `LDFLAGS`.
104
105If you get the tree from the Git repository, you will need to run
106
107 ./bootstrap
108
109in its root. It calls all the GNU tools needed to prepare the tree
110configuration.
111
112To build LTTng-tools, do:
113
114 ./configure
115 make
116 sudo make install
117 sudo ldconfig
118
119If you want Python bindings, add the `--enable-python-bindings` option
120to `configure`. Please note that some distributions will need the
121following environment variables set before running configure:
122
123 export PYTHON="python3"
124 export PYTHON_CONFIG="/usr/bin/python3-config"
125
126
127Using
128-----
129
130Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
131with LTTng tracing. You can also use the `-h` or `--help` option of
132any `lttng` command, e.g.:
133
134 lttng enable-event --help
135
136A network streaming HOWTO can be found in
137[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
138helps you understand how to stream a LTTng 2.x trace.
139
140A Python binding HOWTO can be found in
141[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
142understand how to use the Python module to control LTTng.
143
144
145Contact
146-------
147
04814575 148Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
adf4e918
PP
149
150Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
151
152
153Package contents
154----------------
155
156This 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.
509a8fb5 162 - `lttng-crash`: crash trace viewer.
adf4e918
PP
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.
This page took 0.049172 seconds and 4 git commands to generate.