Commit | Line | Data |
---|---|---|
adf4e918 PP |
1 | LTTng-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 | 7 | LTTng-tools is a set of tools to control [LTTng](https://lttng.org/) |
6345ade6 | 8 | tracing. The project includes the LTTng session daemon, consumer daemon |
adf4e918 PP |
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. | |
ce4d4083 | 26 | - **[`liburcu`](http://www.liburcu.org/) >= 0.9.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 | |
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` | |
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 |
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). | |
adf4e918 PP |
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 | ||
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 |
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 | ||
adf4e918 PP |
95 | If you use GNU gold, which is _not_ mandatory, make sure you have this |
96 | version: | |
97 | ||
1b1af97e | 98 | - **GNU gold >= 2.22** |
adf4e918 PP |
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 | ||
04814575 | 148 | Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com) |
adf4e918 PP |
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. | |
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. |