Fix: Warn the user when enabling an event in a new domain
[lttng-tools.git] / README.md
CommitLineData
adf4e918
PP
1LTTng-tools
2===========
3
4LTTng-tools is a set of tools to control [LTTng](https://lttng.org/)
5tracing. The project includes the LTTng session daemon, consumer damon
6and relay daemon, as well as `liblttng-ctl`, a C library used to
7communicate with the session daemon, and `lttng`, a command line
8interface to `liblttng-ctl`.
9
10
11Requirements and optional dependencies
12--------------------------------------
13
14The following items are _required_ to build and run LTTng-tools
15components:
16
17 - **Linux kernel >= 2.6.27**: for `epoll()` support, at least this
18 version is needed. However, `poll()` is also supported by
19 configuring LTTng-tools with the `--disable-epoll` option. Using
20 that, the kernel version may probably be older, but we can't provide
21 any guarantee. Please let us know if you are able to go lower
22 without any problems.
23 - **[`liburcu`](http://urcu.so/) >= 0.8.0**: userspace RCU library,
24 by Mathieu Desnoyers and Paul E. McKenney.
25 - **`libpopt` >= 1.13**: command line arguments parsing library.
26 - Debian/Ubuntu package: `libpopt-dev`
27 - **`libuuid`**: universally unique ID library
28 - Debian/Ubuntu package: `uuid-dev`
29
30The following items are _optional_ dependencies:
31
32 - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
33 Enables the use of `lttng view` command.
34 - Debian/Ubuntu package: `babeltrace`
35 - **`libxml2` >= 2.7.6**: XML document parsing library. Needed for
36 tracing session configuration saving/loading and machine interface
37 output support.
38 - Debian/Ubuntu package: `libxml2-dev`
39 - **Perl**: needed for `make check` and tests.
40 - **Python >= 3.0**: needed for `make check` and tests.
41 - Debian/Ubuntu package: `python3`
42 - **SWIG >= 2.0** and **Python 3 development headers**: needed for
43 Python bindings
44 (enabled at configure time with the `--enable-python-bindings` option).
45 - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
46 - **modprobe**: needed for automatic LTTng kernel modules loading
47 (kernel tracing).
48 - **bash**: needed for running `make check`.
49
50
51Building
52--------
53
54This source tree is based on the Autotools suite from GNU to simplify
55portability. Here are some things you should have on your system in
56order to compile the Git repository tree:
57
58 - GNU Autotools (Automake >= 1.10, Autoconf >= 2.50,
59 Autoheader >= 2.50; make sure your system-wide `automake` points to
60 a recent version!)
61 - [GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2
62 - Flex >= 2.5.35
63 - Bison >= 2.4
64
65If you use GNU gold, which is _not_ mandatory, make sure you have this
66version:
67
68 - GNU gold >= 2.22
69
70Before this version of GNU gold, we hit a
71[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
72Be advised that with GNU gold, you might have to specify
73`-L/usr/local/lib` in `LDFLAGS`.
74
75If you get the tree from the Git repository, you will need to run
76
77 ./bootstrap
78
79in its root. It calls all the GNU tools needed to prepare the tree
80configuration.
81
82To build LTTng-tools, do:
83
84 ./configure
85 make
86 sudo make install
87 sudo ldconfig
88
89If you want Python bindings, add the `--enable-python-bindings` option
90to `configure`. Please note that some distributions will need the
91following environment variables set before running configure:
92
93 export PYTHON="python3"
94 export PYTHON_CONFIG="/usr/bin/python3-config"
95
96
97Using
98-----
99
100Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
101with LTTng tracing. You can also use the `-h` or `--help` option of
102any `lttng` command, e.g.:
103
104 lttng enable-event --help
105
106A network streaming HOWTO can be found in
107[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
108helps you understand how to stream a LTTng 2.x trace.
109
110A Python binding HOWTO can be found in
111[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
112understand how to use the Python module to control LTTng.
113
114
115Contact
116-------
117
04814575 118Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
adf4e918
PP
119
120Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
121
122
123Package contents
124----------------
125
126This package contains the following elements:
127
128 - `doc`: LTTng-tools documentation.
129 - `include`: the public header files that will be installed on the system.
130 - `src/bin`: source code of LTTng-tools programs.
131 - `lttng-consumerd`: consumer daemon.
132 - `lttng-relayd`: relay daemon.
133 - `lttng-sessiond`: session daemon.
134 - `lttng`: command line interface for LTTng tracing control.
135 - `src/common`: common LTTng-tools source code.
136 - `compat`: compatibility library mostly for FreeBSD and Linux.
137 - `config`: tracing session configuration saving/loading.
138 - `hashtable`: library wrapper over Userspace RCU hashtables.
139 - `health`: health check subsytem.
140 - `index`: CTF index utilities.
141 - `kernel-consumer`: Linux kernel consumer.
142 - `kernel-ctl`: Linux kernel tracer control.
143 - `relayd`: relay daemon control.
144 - `sessiond-comm`: session daemon communication.
145 - `ust-consumer`: user space consumer.
146 - `src/lib`: source code of LTTng-tools libraries.
147 - `lttng-ctl`: LTTng control library.
148 - `tests`: various test programs.
This page took 0.041175 seconds and 4 git commands to generate.