1 // Render with Asciidoctor
6 :bt2: Babeltrace{nbsp}2
9 Babeltrace /ˈbæbəltreɪs/, an
10 https://efficios.com/[EfficiOS] project, is an open-source
11 https://en.wikipedia.org/wiki/Tracing_(software)[trace]
12 manipulation framework.
14 https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]]
15 https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]
17 The **_{bt2}_** project offers a library with a
18 https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[C{nbsp}API],
19 https://diamon.org/babeltrace/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings],
21 https://diamon.org/babeltrace/docs/v{btversion}/man1/babeltrace2.1/[command-line tool]
22 (CLI) which makes it very easy for mere mortals to view, convert,
23 transform, and analyze traces.
25 {bt2} is also the reference parser implementation of the
26 https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile
27 trace format produced by various tracers and tools such as
28 https://lttng.org/[LTTng] and
29 https://barectf.org/[barectf]. The {bt2} library and its Python bindings
30 can read and write CTF traces.
32 See Babeltrace's https://diamon.org/babeltrace[official website], in
34 https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
35 manual page, to learn more about the project.
38 .Babeltrace{nbsp}1 vs. {bt2}
40 The Babeltrace project exists since 2010. In 2019, {bt2} was
41 released. {bt2} is a complete rewrite of the library, Python
42 bindings, and CLI. It is plugin-based and offers much more features and
43 potential than Babeltrace{nbsp}1 while showing comparable performance.
45 Because {bt2} is still a young major release, some
46 distributions still provide packages for the Babeltrace{nbsp}1 project.
47 Both projects can coexist on the same system as there are no common
50 This file documents the **{bt2}** project.
54 == Build Babeltrace{nbsp}{btversion} from source
56 === Build-time requirements
58 To build Babeltrace{nbsp}{btversion}, you need:
61 * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and
62 https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension]
65 https://clang.llvm.org/[Clang] is one of those.
68 * https://www.gnu.org/software/make/[GNU Make]
69 * **If you build from a Git clone**:
70 ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.10
71 ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.64
72 ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2
73 ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35
74 ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.4
77 * A C library (for example,
78 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
79 https://www.musl-libc.org/[musl libc])
80 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
81 (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`)
83 _**If you need the `bt2` Python bindings**_::
84 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development
85 libraries and `python3-config`)
86 (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`)
87 * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0
89 _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_::
90 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
91 (Debian/Ubuntu: `libelf-dev` and `libdw-dev`;
92 Fedora: `elfutils-devel` and `elfutils-libelf-devel`)
94 _**If you need the `bt2` Python bindings documentation**_::
95 * Python{nbsp}≥{nbsp}3.4
96 (Debian/Ubuntu/Fedora: `python3`)
97 * https://www.sphinx-doc.org/en/master/[Sphinx]{nbsp}≥{nbsp}1.6.5
98 for Python{nbsp}3 (Debian/Ubuntu/Fedora: `python3-sphinx`)
100 _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_::
101 * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6
103 _**If you need the {bt2} manual pages**_::
104 * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8
105 * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25
112 . **If you build from a Git clone**, do:
119 This generates the `configure` script and other important files.
121 . [[conf]]Configure the project:
129 The following options can modify the build:
132 Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
134 `--enable-debug-info`::
135 Build the https://lttng.org/[LTTng] debug information filter
137 (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]).
139 `--enable-man-pages`::
140 Build the {bt2} manual pages.
142 `--enable-python-bindings`::
143 Build the `bt2` Python bindings.
145 You can set the path to custom `python3` and `python3-config` programs
146 with the `PYTHON` and `PYTHON_CONFIG` environment variable.
148 `--enable-python-bindings-doc`::
149 Build the `bt2` Python bindings documentation.
151 `--enable-python-plugins`::
152 Build support for {bt2} Python plugins.
154 The following environment variables can modify the build:
156 `BABELTRACE_DEBUG_MODE`::
157 Set to `1` to enable the debug mode.
159 The debug mode enables more run-time assertions to detect bugs in the
162 `BABELTRACE_DEV_MODE`::
163 Set to `1` to enable the <<dev-mode,developer mode>>.
165 The {bt2} developer mode enables more precondition and postcondition
166 assertions to detect programming errors.
168 `BABELTRACE_MINIMAL_LOG_LEVEL`::
169 Set the build-time, minimal logging level for all the project's
172 Set to `TRACE`, `DEBUG`, or `INFO`.
174 `BABELTRACE_PLUGIN_PROVIDERS_DIR`::
175 Installation directory of {bt2} plugin providers.
177 `BABELTRACE_PLUGINS_DIR`::
178 Installation directory of {bt2} project plugins.
180 See `./configure --help` to list all the available options and
181 environment variables.
202 === Build {bt2} for plugin or application development
204 If you are developing a {bt2} plugin or an application which uses
205 libbabeltrace2, we recommend that:
207 * You build {bt2} from source in _developer mode_.
209 The {bt2} developer mode enables more precondition and postcondition
210 assertions to detect programming errors.
212 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
214 * You use _TRACE_ as the minimal logging level at build time to have
215 access to more logging, should you need it to debug your plugin or
218 Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
221 {bt2} development build configuration command line example:
225 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
228 {bt2} development build configuration with Python support example:
232 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
233 --enable-python-bindings --enable-python-plugins
237 https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
238 documentation for more information.
241 == Use Babeltrace{nbsp}{btversion}
243 See the https://diamon.org/babeltrace[Babeltrace website] to learn how
244 to use the different parts of the project.
247 === Run-time requirements
250 * A C library (for example,
251 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
252 https://www.musl-libc.org/[musl libc])
253 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
254 (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
256 _**If you need the `bt2` Python bindings**_::
257 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4
258 (Debian/Ubuntu/Fedora: `python3`)
260 _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_::
261 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
262 (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and
270 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
271 pretty-print their events.
273 Even though Babeltrace is independant from the LTTng project today,
274 their communities remain very close, which is why they share some
275 communication channels and services.
279 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
280 (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
283 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
286 https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
289 https://github.com/efficios/babeltrace/[efficios/babeltrace]
291 Continuous integration::
292 https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build]
296 https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]