kerner-ctl: add RING_RING_BUFFER_GET_NEXT_SUBBUF_METADATA_CHECK
[lttng-tools.git] / README.md
CommitLineData
b77bfe92
PP
1LTTng‑tools
2=================
adf4e918 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
b77bfe92
PP
7_**LTTng‑tools**_ is a set of components to control
8[LTTng](https://lttng.org/) tracing.
9
10The project includes:
11
12* The LTTng [session daemon](https://lttng.org/man/8/lttng-sessiond/).
13* The LTTng consumer daemon.
14* The LTTng [relay daemon](https://lttng.org/man/8/lttng-relayd/).
15* liblttng‑ctl, a library with a C API used to communicate
16 with the session daemon.
17* Python 3 bindings of liblttng‑ctl.
18* [`lttng`](https://lttng.org/man/1/lttng/),
ef315a68 19 a command-line tool over liblttng‑ctl.
b77bfe92 20* [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line
ef315a68 21 tool to recover and view LTTng 2 trace buffers in the event of
b77bfe92
PP
22 a crash.
23
24Required and optional dependencies
25----------------------------------
26You need the following dependencies to build and run the
27LTTng‑tools components:
28
29* **Linux kernel ≥ 2.6.27**
30
31 Use `--disable-epoll` at [build configuration](#configure) time to
32 build LTTng‑tools for an older kernel. However, note that we
33 can't provide any guarantee below 2.6.27.
34
35* **[Userspace RCU](http://www.liburcu.org/) ≥ 0.9.0**.
36
37 Debian/Ubuntu package: `liburcu-dev`.
38
39* **popt ≥ 1.13**
40
41 Debian/Ubuntu package: `libpopt-dev`.
42
43* **[Libxml2](http://xmlsoft.org/) ≥ 2.7.6**
44
45 Debian/Ubuntu package: `libxml2-dev`
46
47The following dependencies are optional:
48
49* **[Babeltrace 2](https://babeltrace.org/)**: default viewer
50 of the [`lttng view`](https://lttng.org/man/1/lttng-view/)
51 command.
52
53 Debian/Ubuntu package: `babeltrace2`
54
55* **[LTTng‑UST](https://lttng.org/)** (same minor version as
56 LTTng‑tools):
57 LTTng user space tracing (applications and libraries).
58
59 Debian/Ubuntu package: `liblttng-ust-dev`
60
61* **Perl**: `make check` and tests.
62
63* **[Python](https://www.python.org/) ≥ 3.0**:
64 `make check` and tests.
65
66 Debian/Ubuntu package: `python3`
67
68* **[SWIG](http://www.swig.org/) ≥ 2.0** and
69 **Python 3 development headers**: Python bindings
70 (enabled at [build configuration](#configure) time with the
71 `--enable-python-bindings` option).
72
73 Debian/Ubuntu packages: `swig2.0` and `python3-dev`
74
75* **modprobe** and/or
76 **[kmod](https://git.kernel.org/pub/scm/utils/kernel/kmod/kmod.git/) ≥ 22**:
77 automatic LTTng kernel modules loading (kernel tracing).
78
79* **Bash**: `make check`.
80
81* **[`man`](http://man7.org/linux/man-pages/man1/man.1.html)**
82 (manual pager): view `lttng` command manual
83 pages with the `--help` option or with the
84 [`lttng help`](https://lttng.org/man/1/lttng-help/) command.
85
86 Note that you can use the [build configuration](#configure) option
87 `--enable-embedded-help` to embed the manual pages into the
88 `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs
89 so that you don't need `man` to view them.
90
91* **[libpfm](http://perfmon2.sourceforge.net/) ≥ 4.0**:
92 perf regression test suite.
93
94 Debian/Ubuntu package: `libpfm4-dev`
95
96LTTng‑tools supports both the LTTng Linux kernel tracer and LTTng
97user space tracer sharing the same _minor_ version. While some minor
98releases do not change the tracer ABIs and _could_ work, no testing is
99performed to ensure that cross-version compatibility is maintained.
100
101You don't need to rebuild or modify applications instrumented with older
102versions of the LTTng‑UST project to make them work with the
103components of the latest LTTng‑tools release.
adf4e918 104
b77bfe92
PP
105See the [LTTng Documentation](https://lttng.org/docs/) for more
106information on versioning.
adf4e918 107
b77bfe92
PP
108Build from source
109-----------------
110### Dependencies
adf4e918 111
b77bfe92 112You need the following tools to build LTTng‑tools:
adf4e918 113
b77bfe92
PP
114* **[GNU Autotools](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html)**
115 (**Automake ≥ 1.10**,
116 **Autoconf ≥ 2.64**, and **Autoheader ≥ 2.50**)
117
118* **[GNU Libtool](http://www.gnu.org/software/autoconf/) ≥ 2.2**
119
120* **[Flex](https://github.com/westes/flex/) ≥ 2.5.35**
121
122* **[Bison](https://www.gnu.org/software/bison/) ≥ 2.4**
123
124To build the LTTng‑tools manual pages:
125
126* **[AsciiDoc](https://www.methods.co.nz/asciidoc/) ≥ 8.4.5**
127
128 Previous versions could work, but were not tested.
129
130* **[xmlto](https://pagure.io/xmlto) ≥ 0.0.21**
131
132 Previous versions could work, but were not tested.
133
134If you use GNU gold, which is _not_ mandatory:
135
136* **GNU gold ≥ 2.22**
137
138Note that with GNU gold, you might have to add
139`-L/usr/local/lib` to the `LDFLAGS` environment variable.
140
141### Build steps
142
1431. **If you have the LTTng‑tools Git source**, run:
144
145 $ ./bootstrap
146
147 This script creates the `configure` script.
148
1492. <span id="configure"></span>Configure the build:
150
151 $ ./configure
152
153 If you want the liblttng&#8209;ctl Python bindings, use the
154 `--enable-python-bindings` option. See also the
155 `PYTHON` and `PYTHON_CONFIG` environment variables in
156 `./configure --help`.
157
158 If you don't want to build the manual pages, use the
159 `--disable-man-pages` option.
160
161 If you want to embed the manual pages into the
162 `lttng`, `lttng-sessiond`, `lttng-relayd`, and `lttng-crash` programs
163 so that you don't need `man` to view them, use the
164 `--enable-embedded-help` option.
165
166 If your Linux kernel is older than 2.6.27, use the
167 `--enable-epoll` option.
168
169 This build configuration script finds LTTng&#8209;UST with
170 [pkg&#8209;config](https://www.freedesktop.org/wiki/Software/pkg-config/):
171 set the `PKG_CONFIG_PATH` environment variable accordingly if
172 pkg&#8209;config cannot find the `lttng-ust` package information.
173
174 See `./configure --help` for the complete list of options.
175
1763. Build the project:
177
178 $ make
179
1804. Install the project:
181
182 $ sudo make install
183 $ sudo ldconfig
184
185Usage
186-----
187See the [Tracing control](https://lttng.org/docs/#doc-controlling-tracing)
188section of the LTTng Documentation to learn how to use the
189LTTng&#8209;tools components.
adf4e918 190
b77bfe92
PP
191See also the [LTTng manual pages](https://lttng.org/man/) (all
192section&nbsp;1 and&nbsp;8 pages).
adf4e918 193
b77bfe92
PP
194As there's no official liblttng&#8209;ctl Python bindings yet, see
195[`doc/python-howto.txt`](doc/python-howto.txt) to understand how to
196use them.
adf4e918 197
b77bfe92
PP
198Community
199---------
200* **Mailing list**:
201 [lttng&#8209;dev](https://lists.lttng.org/cgi-bin/mailman/listinfo).
adf4e918 202
b77bfe92
PP
203* **IRC channel**:
204 [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network.
adf4e918 205
b77bfe92
PP
206* **Bug tracker**::
207 [LTTng&#8209;tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/).
adf4e918 208
b77bfe92
PP
209* **GitHub project**:
210 [lttng/lttng&#8209;tools](https://github.com/lttng/lttng-tools/).
adf4e918 211
b77bfe92
PP
212* **Continuous integration**:
213 [LTTng CI](https://ci.lttng.org/).
adf4e918 214
b77bfe92
PP
215* **Code review**:
216 [_lttng&#8209;tools_ project](https://review.lttng.org/q/project:lttng-tools)
217 on LTTng Review.
This page took 0.04113 seconds and 4 git commands to generate.