Commit | Line | Data |
---|---|---|
94313b56 PP |
1 | // Render with Asciidoctor |
2 | ||
6de042b4 | 3 | = Babeltrace 2 |
9b19ad78 | 4 | 4 March 2024 |
94313b56 PP |
5 | :btversion: 2.0 |
6 | :bt2: Babeltrace{nbsp}2 | |
6de042b4 PP |
7 | ifdef::env-github[] |
8 | :toc: macro | |
9 | endif::[] | |
10 | ifndef::env-github[] | |
11 | :toc: left | |
12 | endif::[] | |
94313b56 PP |
13 | |
14 | Babeltrace /ˈbæbəltreɪs/, an | |
15 | https://efficios.com/[EfficiOS] project, is an open-source | |
16 | https://en.wikipedia.org/wiki/Tracing_(software)[trace] | |
17 | manipulation framework. | |
18 | ||
6de042b4 | 19 | https://ci.lttng.org/job/babeltrace_master_linuxbuild[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_linuxbuild.svg[]] |
94313b56 PP |
20 | https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]] |
21 | ||
22 | The **_{bt2}_** project offers a library with a | |
fe0b4563 PP |
23 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API], |
24 | https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], | |
94313b56 | 25 | and a |
fe0b4563 | 26 | https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool] |
94313b56 PP |
27 | (CLI) which makes it very easy for mere mortals to view, convert, |
28 | transform, and analyze traces. | |
29 | ||
6de042b4 PP |
30 | image::doc/api/libbabeltrace2/images/basic-convert-graph.png[A basic {bt2} conversion graph] |
31 | ||
94313b56 | 32 | {bt2} is also the reference parser implementation of the |
6de042b4 PP |
33 | https://diamon.org/ctf/[Common Trace Format] (CTF), a flexible |
34 | trace format which various tracers and tools such as | |
94313b56 | 35 | https://lttng.org/[LTTng] and |
6de042b4 PP |
36 | https://barectf.org/[barectf] produce natively. |
37 | The {bt2} library and its Python bindings can read and write CTF traces. | |
94313b56 | 38 | |
6de042b4 | 39 | See the {bt2} https://babeltrace.org[official website], in |
94313b56 | 40 | particular the |
fe0b4563 | 41 | https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] |
94313b56 PP |
42 | manual page, to learn more about the project. |
43 | ||
44 | [NOTE] | |
6de042b4 PP |
45 | ifdef::env-github[] |
46 | .**Babeltrace{nbsp}1 vs. {bt2}** | |
47 | endif::[] | |
48 | ifndef::env-github[] | |
94313b56 | 49 | .Babeltrace{nbsp}1 vs. {bt2} |
6de042b4 | 50 | endif::[] |
94313b56 | 51 | ==== |
6de042b4 | 52 | The Babeltrace project exists since 2010. |
94313b56 | 53 | |
6de042b4 PP |
54 | In 2020, {bt2} was released. {bt2} is a complete rewrite of the library, |
55 | Python bindings, and CLI. It's plugin-based and offers much more | |
56 | features and potential than Babeltrace{nbsp}1 while delivering | |
57 | comparable performance. | |
94313b56 | 58 | |
6de042b4 PP |
59 | Some Linux distributions still provide packages for the |
60 | Babeltrace{nbsp}1 project. Both projects can coexist on the same system | |
61 | as there are no conflicting files. | |
62 | ||
63 | This README documents the **{bt2}** project. | |
94313b56 PP |
64 | ==== |
65 | ||
6de042b4 PP |
66 | ifdef::env-github[] |
67 | toc::[] | |
68 | endif::[] | |
94313b56 PP |
69 | |
70 | == Build Babeltrace{nbsp}{btversion} from source | |
71 | ||
72 | === Build-time requirements | |
73 | ||
74 | To build Babeltrace{nbsp}{btversion}, you need: | |
75 | ||
76 | Compiler:: | |
77 | * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and | |
78 | https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension] | |
79 | support. | |
80 | + | |
81 | https://clang.llvm.org/[Clang] is one of those. | |
82 | ||
c20049fd MJ |
83 | * Any {cpp} compiler with {cpp}11 support (for example, |
84 | GCC{nbsp}≥{nbsp}4.8 and Clang{nbsp}≥{nbsp}3.3). | |
85 | ||
94313b56 PP |
86 | Tools:: |
87 | * https://www.gnu.org/software/make/[GNU Make] | |
88 | * **If you build from a Git clone**: | |
82c49689 | 89 | ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.13 |
271fb690 | 90 | ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69 |
94313b56 PP |
91 | ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2 |
92 | ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35 | |
921cd9bd | 93 | ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.5 |
94313b56 PP |
94 | |
95 | Libraries:: | |
96 | * A C library (for example, | |
97 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library], | |
98 | https://www.musl-libc.org/[musl libc]) | |
ef9559ae | 99 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
94313b56 PP |
100 | (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`) |
101 | ||
102 | _**If you need the `bt2` Python bindings**_:: | |
103 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development | |
104 | libraries and `python3-config`) | |
105 | (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`) | |
106 | * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0 | |
107 | ||
fe0b4563 | 108 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: |
94313b56 PP |
109 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 |
110 | (Debian/Ubuntu: `libelf-dev` and `libdw-dev`; | |
111 | Fedora: `elfutils-devel` and `elfutils-libelf-devel`) | |
112 | ||
94313b56 PP |
113 | _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_:: |
114 | * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6 | |
115 | ||
116 | _**If you need the {bt2} manual pages**_:: | |
117 | * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 | |
118 | * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25 | |
119 | ||
ba64dfcc SM |
120 | _**If you need the `bt2` Python bindings documentation**_:: |
121 | * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for | |
122 | Python{nbsp}3 | |
123 | (Debian/Ubuntu/Fedora: `python3-sphinx`) | |
124 | ||
6de042b4 PP |
125 | [NOTE] |
126 | ifdef::env-github[] | |
127 | .**Thanks for the code!** | |
128 | endif::[] | |
129 | ifndef::env-github[] | |
130 | .Thanks for the code! | |
131 | endif::[] | |
132 | ==== | |
133 | We'd like to thank the authors of the following projects which are | |
134 | embedded into the {bt2} source tree: | |
135 | ||
136 | * https://github.com/fmtlib/fmt[\{fmt}] | |
137 | * https://github.com/nlohmann/json[JSON for Modern {cpp}] | |
138 | * https://github.com/martinmoene/optional-lite[optional lite] | |
139 | * https://github.com/martinmoene/span-lite[span lite] | |
9b19ad78 | 140 | * https://github.com/martinmoene/string-view-lite[string_view lite] |
6de042b4 PP |
141 | * https://github.com/wonder-mice/zf_log[zf_log] |
142 | ==== | |
94313b56 PP |
143 | |
144 | === Procedure | |
145 | ||
146 | To build {bt2}: | |
147 | ||
148 | . **If you build from a Git clone**, do: | |
149 | + | |
150 | [role="term"] | |
151 | ---- | |
152 | $ ./bootstrap | |
153 | ---- | |
154 | + | |
155 | This generates the `configure` script and other important files. | |
156 | ||
157 | . [[conf]]Configure the project: | |
158 | + | |
159 | [role="term"] | |
160 | ---- | |
161 | $ ./configure | |
162 | ---- | |
163 | + | |
164 | -- | |
165 | The following options can modify the build: | |
166 | ||
167 | `--enable-api-doc`:: | |
168 | Build the {bt2}{nbsp}C{nbsp}API HTML documentation. | |
169 | ||
6de042b4 PP |
170 | `--enable-built-in-plugins`:: |
171 | Statically link the official plugins into the | |
172 | `babeltrace2` executable. | |
173 | ||
174 | `--enable-built-in-python-plugin-support`:: | |
175 | Statically link the Python plugin provider into the | |
176 | `babeltrace2` executable. | |
177 | ||
94313b56 PP |
178 | `--enable-debug-info`:: |
179 | Build the https://lttng.org/[LTTng] debug information filter | |
180 | component class | |
fe0b4563 | 181 | (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). |
94313b56 PP |
182 | |
183 | `--enable-man-pages`:: | |
184 | Build the {bt2} manual pages. | |
185 | ||
186 | `--enable-python-bindings`:: | |
187 | Build the `bt2` Python bindings. | |
188 | + | |
189 | You can set the path to custom `python3` and `python3-config` programs | |
190 | with the `PYTHON` and `PYTHON_CONFIG` environment variable. | |
191 | ||
192 | `--enable-python-bindings-doc`:: | |
193 | Build the `bt2` Python bindings documentation. | |
194 | ||
195 | `--enable-python-plugins`:: | |
196 | Build support for {bt2} Python plugins. | |
197 | ||
198 | The following environment variables can modify the build: | |
199 | ||
200 | `BABELTRACE_DEBUG_MODE`:: | |
201 | Set to `1` to enable the debug mode. | |
202 | + | |
6de042b4 PP |
203 | The debug mode enables more run-time assertions to detect bugs while |
204 | developing the {bt2} project. | |
94313b56 PP |
205 | |
206 | `BABELTRACE_DEV_MODE`:: | |
207 | Set to `1` to enable the <<dev-mode,developer mode>>. | |
208 | + | |
209 | The {bt2} developer mode enables more precondition and postcondition | |
6de042b4 | 210 | assertions to detect C{nbsp}API usage errors. |
94313b56 PP |
211 | |
212 | `BABELTRACE_MINIMAL_LOG_LEVEL`:: | |
6de042b4 PP |
213 | Set the build-time, minimal logging level for all the modules |
214 | of the project. | |
94313b56 PP |
215 | + |
216 | Set to `TRACE`, `DEBUG`, or `INFO`. | |
217 | ||
218 | `BABELTRACE_PLUGIN_PROVIDERS_DIR`:: | |
219 | Installation directory of {bt2} plugin providers. | |
220 | ||
221 | `BABELTRACE_PLUGINS_DIR`:: | |
6de042b4 | 222 | Installation directory of {bt2} official plugins. |
94313b56 | 223 | |
6de042b4 | 224 | Run `./configure --help` to list all the available options and |
94313b56 PP |
225 | environment variables. |
226 | -- | |
227 | ||
228 | . Build {bt2}: | |
229 | + | |
230 | [role="term"] | |
231 | ---- | |
232 | $ make | |
233 | ---- | |
234 | ||
235 | To install {bt2}: | |
236 | ||
6de042b4 | 237 | * Run: |
94313b56 PP |
238 | + |
239 | [role="term"] | |
240 | ---- | |
241 | # make install | |
242 | ---- | |
243 | ||
94313b56 PP |
244 | [[dev-mode]] |
245 | === Build {bt2} for plugin or application development | |
246 | ||
6de042b4 PP |
247 | If you're developing a {bt2} plugin or an application which uses |
248 | libbabeltrace2, we recommend to: | |
94313b56 | 249 | |
6de042b4 | 250 | * Build {bt2} from source in _developer mode_. |
94313b56 PP |
251 | + |
252 | The {bt2} developer mode enables more precondition and postcondition | |
6de042b4 PP |
253 | assertions to detect C{nbsp}API usage errors. |
254 | + | |
255 | The | |
256 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API documentation] | |
257 | always lists the precondition and postconditions of | |
258 | functions. | |
94313b56 PP |
259 | + |
260 | Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build. | |
261 | ||
6de042b4 | 262 | * Use _TRACE_ as the minimal logging level at build time to have |
94313b56 PP |
263 | access to more logging, should you need it to debug your plugin or |
264 | application. | |
265 | + | |
266 | Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>> | |
267 | the {bt2} build. | |
268 | ||
269 | {bt2} development build configuration command line example: | |
270 | ||
271 | [role="term"] | |
272 | ---- | |
273 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure | |
274 | ---- | |
275 | ||
276 | {bt2} development build configuration with Python support example: | |
277 | ||
278 | [role="term"] | |
279 | ---- | |
280 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ | |
281 | --enable-python-bindings --enable-python-plugins | |
282 | ---- | |
283 | ||
284 | See the | |
6de042b4 PP |
285 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API |
286 | documentation] for more information. | |
94313b56 PP |
287 | |
288 | == Use Babeltrace{nbsp}{btversion} | |
289 | ||
6de042b4 PP |
290 | See the https://babeltrace.org[{bt2} website] to learn how to use the |
291 | different parts of the project. | |
94313b56 | 292 | |
6de042b4 PP |
293 | If you're new to {bt2}, make sure to read the |
294 | https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] | |
295 | manual page to familiarize yourself with the project. | |
94313b56 PP |
296 | |
297 | === Run-time requirements | |
298 | ||
6de042b4 PP |
299 | Libraries:: {empty} |
300 | + | |
301 | * A C library (for example, | |
302 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library] or | |
303 | https://www.musl-libc.org/[musl libc]) | |
94313b56 | 304 | |
6de042b4 PP |
305 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
306 | (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) | |
94313b56 | 307 | |
6de042b4 PP |
308 | _**If you need the `bt2` Python bindings**_:: {empty} |
309 | + | |
310 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 | |
311 | (Debian/Ubuntu/Fedora: `python3`) | |
94313b56 | 312 | |
6de042b4 PP |
313 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: {empty} |
314 | + | |
315 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 | |
316 | (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and | |
317 | `elfutils-libelf`) | |
94313b56 PP |
318 | |
319 | == Community | |
320 | ||
94313b56 | 321 | Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and |
6de042b4 | 322 | to pretty-print their events. |
94313b56 | 323 | |
6de042b4 PP |
324 | Even though {bt2} is independent from the LTTng project today, their |
325 | communities remain very close, which is why they share some | |
326 | communication channels and services: | |
94313b56 PP |
327 | |
328 | Mailing list:: | |
329 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] | |
330 | (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) | |
331 | ||
332 | IRC channel:: | |
333 | irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network | |
334 | ||
335 | Bug tracker:: | |
6de042b4 | 336 | https://bugs.lttng.org/projects/babeltrace[{bt2} bug tracker] |
94313b56 PP |
337 | |
338 | GitHub project:: | |
339 | https://github.com/efficios/babeltrace/[efficios/babeltrace] | |
340 | ||
341 | Continuous integration:: | |
6de042b4 PP |
342 | https://ci.lttng.org/view/Babeltrace/[{bt2} jobs] |
343 | on the LTTng CI | |
94313b56 PP |
344 | |
345 | Code review:: | |
6de042b4 PP |
346 | https://review.lttng.org/q/project:babeltrace[{bt2} project] |
347 | on LTTng Review (Gerrit) |