Commit | Line | Data |
---|---|---|
b77bfe92 PP |
1 | LTTng‑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 | ||
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/), | |
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 | ||
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. | |
adf4e918 | 104 | |
b77bfe92 PP |
105 | See the [LTTng Documentation](https://lttng.org/docs/) for more |
106 | information on versioning. | |
adf4e918 | 107 | |
b77bfe92 PP |
108 | Build from source |
109 | ----------------- | |
110 | ### Dependencies | |
adf4e918 | 111 | |
b77bfe92 | 112 | You 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 | ||
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‑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‑UST with | |
170 | [pkg‑config](https://www.freedesktop.org/wiki/Software/pkg-config/): | |
171 | set the `PKG_CONFIG_PATH` environment variable accordingly if | |
172 | pkg‑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‑tools components. | |
adf4e918 | 190 | |
b77bfe92 PP |
191 | See also the [LTTng manual pages](https://lttng.org/man/) (all |
192 | section 1 and 8 pages). | |
adf4e918 | 193 | |
b77bfe92 PP |
194 | As there's no official liblttng‑ctl Python bindings yet, see |
195 | [`doc/python-howto.txt`](doc/python-howto.txt) to understand how to | |
196 | use them. | |
adf4e918 | 197 | |
b77bfe92 PP |
198 | Community |
199 | --------- | |
200 | * **Mailing list**: | |
201 | [lttng‑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‑tools bug tracker](https://bugs.lttng.org/projects/lttng-tools/). | |
adf4e918 | 208 | |
b77bfe92 PP |
209 | * **GitHub project**: |
210 | [lttng/lttng‑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‑tools_ project](https://review.lttng.org/q/project:lttng-tools) | |
217 | on LTTng Review. |