Commit | Line | Data |
---|---|---|
adf4e918 PP |
1 | LTTng-tools |
2 | =========== | |
3 | ||
4 | LTTng-tools is a set of tools to control [LTTng](https://lttng.org/) | |
5 | tracing. The project includes the LTTng session daemon, consumer damon | |
6 | and relay daemon, as well as `liblttng-ctl`, a C library used to | |
7 | communicate with the session daemon, and `lttng`, a command line | |
8 | interface to `liblttng-ctl`. | |
9 | ||
10 | ||
11 | Requirements and optional dependencies | |
12 | -------------------------------------- | |
13 | ||
14 | The following items are _required_ to build and run LTTng-tools | |
15 | components: | |
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 | ||
30 | The 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 | ||
51 | Building | |
52 | -------- | |
53 | ||
54 | This source tree is based on the Autotools suite from GNU to simplify | |
55 | portability. Here are some things you should have on your system in | |
56 | order 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 | ||
65 | If you use GNU gold, which is _not_ mandatory, make sure you have this | |
66 | version: | |
67 | ||
68 | - GNU gold >= 2.22 | |
69 | ||
70 | Before this version of GNU gold, we hit a | |
71 | [known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317). | |
72 | Be advised that with GNU gold, you might have to specify | |
73 | `-L/usr/local/lib` in `LDFLAGS`. | |
74 | ||
75 | If you get the tree from the Git repository, you will need to run | |
76 | ||
77 | ./bootstrap | |
78 | ||
79 | in its root. It calls all the GNU tools needed to prepare the tree | |
80 | configuration. | |
81 | ||
82 | To build LTTng-tools, do: | |
83 | ||
84 | ./configure | |
85 | make | |
86 | sudo make install | |
87 | sudo ldconfig | |
88 | ||
89 | If you want Python bindings, add the `--enable-python-bindings` option | |
90 | to `configure`. Please note that some distributions will need the | |
91 | following environment variables set before running configure: | |
92 | ||
93 | export PYTHON="python3" | |
94 | export PYTHON_CONFIG="/usr/bin/python3-config" | |
95 | ||
96 | ||
97 | Using | |
98 | ----- | |
99 | ||
100 | Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started | |
101 | with LTTng tracing. You can also use the `-h` or `--help` option of | |
102 | any `lttng` command, e.g.: | |
103 | ||
104 | lttng enable-event --help | |
105 | ||
106 | A network streaming HOWTO can be found in | |
107 | [`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly | |
108 | helps you understand how to stream a LTTng 2.x trace. | |
109 | ||
110 | A Python binding HOWTO can be found in | |
111 | [`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you | |
112 | understand how to use the Python module to control LTTng. | |
113 | ||
114 | ||
115 | Contact | |
116 | ------- | |
117 | ||
118 | Maintainer: [David Goulet](mailto:dgoulet@efficios.com) | |
119 | ||
120 | Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev) | |
121 | ||
122 | ||
123 | Package contents | |
124 | ---------------- | |
125 | ||
126 | This 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. |