README.md: add lttng-crash in package contents
[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.
99ad3285 23 - **[`liburcu`](http://www.liburcu.org/) >= 0.8.0**: userspace RCU library,
adf4e918
PP
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`
2199563c
JG
29 - **`libxml2` >= 2.7.6**: XML document parsing library. Needed for
30 tracing session configuration saving/loading and machine interface
31 output support.
32 - Debian/Ubuntu package: `libxml2-dev`
33
adf4e918
PP
34
35The following items are _optional_ dependencies:
36
37 - **[Babeltrace](https://lttng.org/babeltrace)**: trace viewer.
38 Enables the use of `lttng view` command.
39 - Debian/Ubuntu package: `babeltrace`
4c780623
JG
40 - **[LTTng UST](https://lttng.org) (same minor version as LTTng Tools)**:
41 userspace tracer. Enables the tracing of userspace applications.
213ff7c7 42 - Debian/Ubuntu package: `liblttng-ust-dev`
adf4e918
PP
43 - **Perl**: needed for `make check` and tests.
44 - **Python >= 3.0**: needed for `make check` and tests.
45 - Debian/Ubuntu package: `python3`
46 - **SWIG >= 2.0** and **Python 3 development headers**: needed for
47 Python bindings
48 (enabled at configure time with the `--enable-python-bindings` option).
49 - Debian/Ubuntu packages: `swig2.0` and `python3-dev`
50 - **modprobe**: needed for automatic LTTng kernel modules loading
51 (kernel tracing).
52 - **bash**: needed for running `make check`.
d1bec732
PP
53 - **man** (manual pager): needed to view LTTng-tools commands' man
54 pages with the `--help` option or with the `lttng help` command.
55 Note that without `man`, you cannot get offline help with
56 LTTng-tools commands, not even their usage.
adf4e918 57
4c780623
JG
58LTTng-tools supports both the [LTTng Linux Kernel tracer](https://lttng.org)
59and [LTTng user space tracer](https://lttng.org) released as part of the same
60**minor** release series. While some releases do not change the tracer ABIs and
61should work with, no testing is performed to ensure cross-version compatibility
62is maintained.
63
64Note that applications instrumented with older versions of the LTTng UST project
65do not have to be rebuilt or modified to work with the latest LTTng-tools.
66For more information on versioning, please refer to the
67[LTTng documentation](https://lttng.org/docs).
adf4e918
PP
68
69Building
70--------
71
72This source tree is based on the Autotools suite from GNU to simplify
73portability. Here are some things you should have on your system in
74order to compile the Git repository tree:
75
1b1af97e
PP
76 - **GNU Autotools** (**Automake >= 1.10**, **Autoconf >= 2.64**,
77 **Autoheader >= 2.50**; make sure your system-wide `automake` points
78 to a recent version!)
79 - **[GNU Libtool](http://www.gnu.org/software/autoconf/) >= 2.2**
80 - **Flex >= 2.5.35**
81 - **Bison >= 2.4**
adf4e918 82
8558f6a2
PP
83Optional packages to build LTTng-tools man pages:
84
85 - **AsciiDoc >= 8.4.5** (previous versions may work, but were
86 not tested)
87 - **xmlto >= 0.0.21** (previous versions may work, but were
88 not tested)
89
adf4e918
PP
90If you use GNU gold, which is _not_ mandatory, make sure you have this
91version:
92
1b1af97e 93 - **GNU gold >= 2.22**
adf4e918
PP
94
95Before this version of GNU gold, we hit a
96[known bug](http://sourceware.org/bugzilla/show_bug.cgi?id=11317).
97Be advised that with GNU gold, you might have to specify
98`-L/usr/local/lib` in `LDFLAGS`.
99
100If you get the tree from the Git repository, you will need to run
101
102 ./bootstrap
103
104in its root. It calls all the GNU tools needed to prepare the tree
105configuration.
106
107To build LTTng-tools, do:
108
109 ./configure
110 make
111 sudo make install
112 sudo ldconfig
113
114If you want Python bindings, add the `--enable-python-bindings` option
115to `configure`. Please note that some distributions will need the
116following environment variables set before running configure:
117
118 export PYTHON="python3"
119 export PYTHON_CONFIG="/usr/bin/python3-config"
120
121
122Using
123-----
124
125Please see [`doc/quickstart.txt`](doc/quickstart.txt) to get started
126with LTTng tracing. You can also use the `-h` or `--help` option of
127any `lttng` command, e.g.:
128
129 lttng enable-event --help
130
131A network streaming HOWTO can be found in
132[`doc/streaming-howto.txt`](doc/streaming-howto.txt) which quickly
133helps you understand how to stream a LTTng 2.x trace.
134
135A Python binding HOWTO can be found in
136[`doc/python-howto.txt`](doc/python-howto.txt) which quickly helps you
137understand how to use the Python module to control LTTng.
138
139
140Contact
141-------
142
04814575 143Maintainer: [Jérémie Galarneau](mailto:jeremie.galarneau@efficios.com)
adf4e918
PP
144
145Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
146
147
148Package contents
149----------------
150
151This package contains the following elements:
152
153 - `doc`: LTTng-tools documentation.
154 - `include`: the public header files that will be installed on the system.
155 - `src/bin`: source code of LTTng-tools programs.
156 - `lttng-consumerd`: consumer daemon.
509a8fb5 157 - `lttng-crash`: crash trace viewer.
adf4e918
PP
158 - `lttng-relayd`: relay daemon.
159 - `lttng-sessiond`: session daemon.
160 - `lttng`: command line interface for LTTng tracing control.
161 - `src/common`: common LTTng-tools source code.
162 - `compat`: compatibility library mostly for FreeBSD and Linux.
163 - `config`: tracing session configuration saving/loading.
164 - `hashtable`: library wrapper over Userspace RCU hashtables.
165 - `health`: health check subsytem.
166 - `index`: CTF index utilities.
167 - `kernel-consumer`: Linux kernel consumer.
168 - `kernel-ctl`: Linux kernel tracer control.
169 - `relayd`: relay daemon control.
170 - `sessiond-comm`: session daemon communication.
171 - `ust-consumer`: user space consumer.
172 - `src/lib`: source code of LTTng-tools libraries.
173 - `lttng-ctl`: LTTng control library.
174 - `tests`: various test programs.
This page took 0.051411 seconds and 5 git commands to generate.