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