// Render with Asciidoctor = Babeltrace 13 April 2020 :btversion: 2.0 :bt2: Babeltrace{nbsp}2 Babeltrace /ˈbæbəltreɪs/, an https://efficios.com/[EfficiOS] project, is an open-source https://en.wikipedia.org/wiki/Tracing_(software)[trace] manipulation framework. https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]] https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]] The **_{bt2}_** project offers a library with a https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API], https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], and a https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool] (CLI) which makes it very easy for mere mortals to view, convert, transform, and analyze traces. {bt2} is also the reference parser implementation of the https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile trace format produced by various tracers and tools such as https://lttng.org/[LTTng] and https://barectf.org/[barectf]. The {bt2} library and its Python bindings can read and write CTF traces. See Babeltrace's https://babeltrace.org[official website], in particular the https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] manual page, to learn more about the project. [NOTE] .Babeltrace{nbsp}1 vs. {bt2} ==== The Babeltrace project exists since 2010. In 2020, {bt2} was released. {bt2} is a complete rewrite of the library, Python bindings, and CLI. It is plugin-based and offers much more features and potential than Babeltrace{nbsp}1 while showing comparable performance. Because {bt2} is still a young major release, some distributions still provide packages for the Babeltrace{nbsp}1 project. Both projects can coexist on the same system as there are no common files. This file documents the **{bt2}** project. ==== == Build Babeltrace{nbsp}{btversion} from source === Build-time requirements To build Babeltrace{nbsp}{btversion}, you need: Compiler:: * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension] support. + https://clang.llvm.org/[Clang] is one of those. * Any {cpp} compiler with {cpp}11 support (for example, GCC{nbsp}≥{nbsp}4.8 and Clang{nbsp}≥{nbsp}3.3). Tools:: * https://www.gnu.org/software/make/[GNU Make] * **If you build from a Git clone**: ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.12 ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69 ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2 ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35 ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.4 Libraries:: * A C library (for example, https://www.gnu.org/software/libc/[GNU{nbsp}C Library], https://www.musl-libc.org/[musl libc]) * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`) _**If you need the `bt2` Python bindings**_:: * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development libraries and `python3-config`) (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`) * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0 _**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`])**_:: * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 (Debian/Ubuntu: `libelf-dev` and `libdw-dev`; Fedora: `elfutils-devel` and `elfutils-libelf-devel`) _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_:: * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6 _**If you need the {bt2} manual pages**_:: * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25 _**If you need the `bt2` Python bindings documentation**_:: * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for Python{nbsp}3 (Debian/Ubuntu/Fedora: `python3-sphinx`) === Procedure To build {bt2}: . **If you build from a Git clone**, do: + [role="term"] ---- $ ./bootstrap ---- + This generates the `configure` script and other important files. . [[conf]]Configure the project: + [role="term"] ---- $ ./configure ---- + -- The following options can modify the build: `--enable-api-doc`:: Build the {bt2}{nbsp}C{nbsp}API HTML documentation. `--enable-debug-info`:: Build 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`]). `--enable-man-pages`:: Build the {bt2} manual pages. `--enable-python-bindings`:: Build the `bt2` Python bindings. + You can set the path to custom `python3` and `python3-config` programs with the `PYTHON` and `PYTHON_CONFIG` environment variable. `--enable-python-bindings-doc`:: Build the `bt2` Python bindings documentation. `--enable-python-plugins`:: Build support for {bt2} Python plugins. The following environment variables can modify the build: `BABELTRACE_DEBUG_MODE`:: Set to `1` to enable the debug mode. + The debug mode enables more run-time assertions to detect bugs in the {bt2} project. `BABELTRACE_DEV_MODE`:: Set to `1` to enable the <>. + The {bt2} developer mode enables more precondition and postcondition assertions to detect programming errors. `BABELTRACE_MINIMAL_LOG_LEVEL`:: Set the build-time, minimal logging level for all the project's modules. + Set to `TRACE`, `DEBUG`, or `INFO`. `BABELTRACE_PLUGIN_PROVIDERS_DIR`:: Installation directory of {bt2} plugin providers. `BABELTRACE_PLUGINS_DIR`:: Installation directory of {bt2} project plugins. See `./configure --help` to list all the available options and environment variables. -- . Build {bt2}: + [role="term"] ---- $ make ---- To install {bt2}: * Do: + [role="term"] ---- # make install ---- [[dev-mode]] === Build {bt2} for plugin or application development If you are developing a {bt2} plugin or an application which uses libbabeltrace2, we recommend that: * You build {bt2} from source in _developer mode_. + The {bt2} developer mode enables more precondition and postcondition assertions to detect programming errors. + Set `BABELTRACE_DEV_MODE=1` when you <> the {bt2} build. * You use _TRACE_ as the minimal logging level at build time to have access to more logging, should you need it to debug your plugin or application. + Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <> the {bt2} build. {bt2} development build configuration command line example: [role="term"] ---- $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure ---- {bt2} development build configuration with Python support example: [role="term"] ---- $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ --enable-python-bindings --enable-python-plugins ---- See the https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] documentation for more information. == Use Babeltrace{nbsp}{btversion} See the https://babeltrace.org[Babeltrace website] to learn how to use the different parts of the project. === Run-time requirements Libraries:: * A C library (for example, https://www.gnu.org/software/libc/[GNU{nbsp}C Library], https://www.musl-libc.org/[musl libc]) * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) _**If you need the `bt2` Python bindings**_:: * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (Debian/Ubuntu/Fedora: `python3`) _**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`])**_:: * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and `elfutils-libelf`) == Community [NOTE] ==== Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and pretty-print their events. Even though Babeltrace is independent from the LTTng project today, their communities remain very close, which is why they share some communication channels and services. ==== Mailing list:: https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) IRC channel:: irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network Bug tracker:: https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker] GitHub project:: https://github.com/efficios/babeltrace/[efficios/babeltrace] Continuous integration:: https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build] on LTTng's CI Code review:: https://review.lttng.org/q/project:babeltrace[_babeltrace_ project] on LTTng Review