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] |
8ae5c2b2 | 141 | * https://github.com/quicknir/wise_enum[wise_enum] |
6de042b4 PP |
142 | * https://github.com/wonder-mice/zf_log[zf_log] |
143 | ==== | |
94313b56 PP |
144 | |
145 | === Procedure | |
146 | ||
147 | To build {bt2}: | |
148 | ||
149 | . **If you build from a Git clone**, do: | |
150 | + | |
151 | [role="term"] | |
152 | ---- | |
153 | $ ./bootstrap | |
154 | ---- | |
155 | + | |
156 | This generates the `configure` script and other important files. | |
157 | ||
158 | . [[conf]]Configure the project: | |
159 | + | |
160 | [role="term"] | |
161 | ---- | |
162 | $ ./configure | |
163 | ---- | |
164 | + | |
165 | -- | |
166 | The following options can modify the build: | |
167 | ||
168 | `--enable-api-doc`:: | |
169 | Build the {bt2}{nbsp}C{nbsp}API HTML documentation. | |
170 | ||
6de042b4 PP |
171 | `--enable-built-in-plugins`:: |
172 | Statically link the official plugins into the | |
173 | `babeltrace2` executable. | |
174 | ||
175 | `--enable-built-in-python-plugin-support`:: | |
176 | Statically link the Python plugin provider into the | |
177 | `babeltrace2` executable. | |
178 | ||
94313b56 PP |
179 | `--enable-debug-info`:: |
180 | Build the https://lttng.org/[LTTng] debug information filter | |
181 | component class | |
fe0b4563 | 182 | (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). |
94313b56 PP |
183 | |
184 | `--enable-man-pages`:: | |
185 | Build the {bt2} manual pages. | |
186 | ||
187 | `--enable-python-bindings`:: | |
188 | Build the `bt2` Python bindings. | |
189 | + | |
190 | You can set the path to custom `python3` and `python3-config` programs | |
191 | with the `PYTHON` and `PYTHON_CONFIG` environment variable. | |
192 | ||
193 | `--enable-python-bindings-doc`:: | |
194 | Build the `bt2` Python bindings documentation. | |
195 | ||
196 | `--enable-python-plugins`:: | |
197 | Build support for {bt2} Python plugins. | |
198 | ||
199 | The following environment variables can modify the build: | |
200 | ||
201 | `BABELTRACE_DEBUG_MODE`:: | |
202 | Set to `1` to enable the debug mode. | |
203 | + | |
6de042b4 PP |
204 | The debug mode enables more run-time assertions to detect bugs while |
205 | developing the {bt2} project. | |
94313b56 PP |
206 | |
207 | `BABELTRACE_DEV_MODE`:: | |
208 | Set to `1` to enable the <<dev-mode,developer mode>>. | |
209 | + | |
210 | The {bt2} developer mode enables more precondition and postcondition | |
6de042b4 | 211 | assertions to detect C{nbsp}API usage errors. |
94313b56 PP |
212 | |
213 | `BABELTRACE_MINIMAL_LOG_LEVEL`:: | |
6de042b4 PP |
214 | Set the build-time, minimal logging level for all the modules |
215 | of the project. | |
94313b56 PP |
216 | + |
217 | Set to `TRACE`, `DEBUG`, or `INFO`. | |
218 | ||
219 | `BABELTRACE_PLUGIN_PROVIDERS_DIR`:: | |
220 | Installation directory of {bt2} plugin providers. | |
221 | ||
222 | `BABELTRACE_PLUGINS_DIR`:: | |
6de042b4 | 223 | Installation directory of {bt2} official plugins. |
94313b56 | 224 | |
6de042b4 | 225 | Run `./configure --help` to list all the available options and |
94313b56 PP |
226 | environment variables. |
227 | -- | |
228 | ||
229 | . Build {bt2}: | |
230 | + | |
231 | [role="term"] | |
232 | ---- | |
233 | $ make | |
234 | ---- | |
235 | ||
236 | To install {bt2}: | |
237 | ||
6de042b4 | 238 | * Run: |
94313b56 PP |
239 | + |
240 | [role="term"] | |
241 | ---- | |
242 | # make install | |
243 | ---- | |
244 | ||
94313b56 PP |
245 | [[dev-mode]] |
246 | === Build {bt2} for plugin or application development | |
247 | ||
6de042b4 PP |
248 | If you're developing a {bt2} plugin or an application which uses |
249 | libbabeltrace2, we recommend to: | |
94313b56 | 250 | |
6de042b4 | 251 | * Build {bt2} from source in _developer mode_. |
94313b56 PP |
252 | + |
253 | The {bt2} developer mode enables more precondition and postcondition | |
6de042b4 PP |
254 | assertions to detect C{nbsp}API usage errors. |
255 | + | |
256 | The | |
257 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API documentation] | |
258 | always lists the precondition and postconditions of | |
259 | functions. | |
94313b56 PP |
260 | + |
261 | Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build. | |
262 | ||
6de042b4 | 263 | * Use _TRACE_ as the minimal logging level at build time to have |
94313b56 PP |
264 | access to more logging, should you need it to debug your plugin or |
265 | application. | |
266 | + | |
267 | Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>> | |
268 | the {bt2} build. | |
269 | ||
270 | {bt2} development build configuration command line example: | |
271 | ||
272 | [role="term"] | |
273 | ---- | |
274 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure | |
275 | ---- | |
276 | ||
277 | {bt2} development build configuration with Python support example: | |
278 | ||
279 | [role="term"] | |
280 | ---- | |
281 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ | |
282 | --enable-python-bindings --enable-python-plugins | |
283 | ---- | |
284 | ||
285 | See the | |
6de042b4 PP |
286 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API |
287 | documentation] for more information. | |
94313b56 PP |
288 | |
289 | == Use Babeltrace{nbsp}{btversion} | |
290 | ||
6de042b4 PP |
291 | See the https://babeltrace.org[{bt2} website] to learn how to use the |
292 | different parts of the project. | |
94313b56 | 293 | |
6de042b4 PP |
294 | If you're new to {bt2}, make sure to read the |
295 | https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] | |
296 | manual page to familiarize yourself with the project. | |
94313b56 PP |
297 | |
298 | === Run-time requirements | |
299 | ||
6de042b4 PP |
300 | Libraries:: {empty} |
301 | + | |
302 | * A C library (for example, | |
303 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library] or | |
304 | https://www.musl-libc.org/[musl libc]) | |
94313b56 | 305 | |
6de042b4 PP |
306 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
307 | (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) | |
94313b56 | 308 | |
6de042b4 PP |
309 | _**If you need the `bt2` Python bindings**_:: {empty} |
310 | + | |
311 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 | |
312 | (Debian/Ubuntu/Fedora: `python3`) | |
94313b56 | 313 | |
6de042b4 PP |
314 | _**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} |
315 | + | |
316 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 | |
317 | (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and | |
318 | `elfutils-libelf`) | |
94313b56 PP |
319 | |
320 | == Community | |
321 | ||
94313b56 | 322 | Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and |
6de042b4 | 323 | to pretty-print their events. |
94313b56 | 324 | |
6de042b4 PP |
325 | Even though {bt2} is independent from the LTTng project today, their |
326 | communities remain very close, which is why they share some | |
327 | communication channels and services: | |
94313b56 PP |
328 | |
329 | Mailing list:: | |
330 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] | |
331 | (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) | |
332 | ||
333 | IRC channel:: | |
334 | irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network | |
335 | ||
336 | Bug tracker:: | |
6de042b4 | 337 | https://bugs.lttng.org/projects/babeltrace[{bt2} bug tracker] |
94313b56 PP |
338 | |
339 | GitHub project:: | |
340 | https://github.com/efficios/babeltrace/[efficios/babeltrace] | |
341 | ||
342 | Continuous integration:: | |
6de042b4 PP |
343 | https://ci.lttng.org/view/Babeltrace/[{bt2} jobs] |
344 | on the LTTng CI | |
94313b56 PP |
345 | |
346 | Code review:: | |
6de042b4 PP |
347 | https://review.lttng.org/q/project:babeltrace[{bt2} project] |
348 | on LTTng Review (Gerrit) |