Fix: consumerd: uninitialized written_bytes on no-data sleep
[lttng-tools.git] / README.md
1 LTTng‑tools
2 =================
3
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
7 _**LTTng‑tools**_ is a set of components to control
8 [LTTng](https://lttng.org/) tracing.
9
10 The 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/),
19 a command-line tool over liblttng‑ctl.
20 * [`lttng-crash`](https://lttng.org/man/1/lttng-crash/), a command-line
21 tool to recover and view LTTng 2 trace buffers in the event of
22 a crash.
23
24 Required and optional dependencies
25 ----------------------------------
26 You need the following dependencies to build and run the
27 LTTng‑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
47 The 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
96 LTTng‑tools supports both the LTTng Linux kernel tracer and LTTng
97 user space tracer sharing the same _minor_ version. While some minor
98 releases do not change the tracer ABIs and _could_ work, no testing is
99 performed to ensure that cross-version compatibility is maintained.
100
101 You don't need to rebuild or modify applications instrumented with older
102 versions of the LTTng‑UST project to make them work with the
103 components of the latest LTTng‑tools release.
104
105 See the [LTTng Documentation](https://lttng.org/docs/) for more
106 information on versioning.
107
108 Build from source
109 -----------------
110 ### Dependencies
111
112 You need the following tools to build LTTng‑tools:
113
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
124 To 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
134 If you use GNU gold, which is _not_ mandatory:
135
136 * **GNU gold ≥ 2.22**
137
138 Note that with GNU gold, you might have to add
139 `-L/usr/local/lib` to the `LDFLAGS` environment variable.
140
141 ### Build steps
142
143 1. **If you have the LTTng‑tools Git source**, run:
144
145 $ ./bootstrap
146
147 This script creates the `configure` script.
148
149 2. <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
176 3. Build the project:
177
178 $ make
179
180 4. Install the project:
181
182 $ sudo make install
183 $ sudo ldconfig
184
185 Usage
186 -----
187 See the [Tracing control](https://lttng.org/docs/#doc-controlling-tracing)
188 section of the LTTng Documentation to learn how to use the
189 LTTng&#8209;tools components.
190
191 See also the [LTTng manual pages](https://lttng.org/man/) (all
192 section&nbsp;1 and&nbsp;8 pages).
193
194 As there's no official liblttng&#8209;ctl Python bindings yet, see
195 [`doc/python-howto.txt`](doc/python-howto.txt) to understand how to
196 use them.
197
198 Community
199 ---------
200 * **Mailing list**:
201 [lttng&#8209;dev](https://lists.lttng.org/cgi-bin/mailman/listinfo).
202
203 * **IRC channel**:
204 [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network.
205
206 * **Bug tracker**::
207 [LTTng&#8209;tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/).
208
209 * **GitHub project**:
210 [lttng/lttng&#8209;tools](https://github.com/lttng/lttng-tools/).
211
212 * **Continuous integration**:
213 [LTTng CI](https://ci.lttng.org/).
214
215 * **Code review**:
216 [_lttng&#8209;tools_ project](https://review.lttng.org/q/project:lttng-tools)
217 on LTTng Review.
This page took 0.050867 seconds and 4 git commands to generate.