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