Commit | Line | Data |
---|---|---|
ae403e46 PP |
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 | ||
87900062 | 61 | * **http://www.liburcu.org/[Userspace{nbsp}RCU]{nbsp}≥{nbsp}0.11.0**. |
ae403e46 PP |
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 | |
c125de8f FD |
76 | of the https://lttng.org/man/1/lttng-view/[`lttng view`] command, |
77 | `make{nbsp}check` and tests. | |
ae403e46 PP |
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 |