Table of Contents

• Build Babeltrace 2.1 from source
  • Build-time requirements
  • Procedure
  • Build Babeltrace 2 for plugin or application development
• Use Babeltrace 2.1
  • Run-time requirements
• Community

Babeltrace /ˈbæbəltreɪs/, an EfficiOS project, is an open-source trace manipulation framework.

The Babeltrace 2 project offers a library with a C API, Python 3 bindings, and a command-line tool (CLI) which makes it very easy for mere mortals to view, convert, transform, and analyze traces.

Babeltrace 2 is also the reference parser implementation of the Common Trace Format (CTF), a flexible trace format which various tracers and tools such as LTTng and barectf produce natively. The Babeltrace 2 library and its Python bindings can read and write CTF traces.

See the Babeltrace 2 official website, in particular the babeltrace2-intro(7) manual page, to learn more about the project.

Note

Babeltrace 1 vs. Babeltrace 2 The Babeltrace project exists since 2010. In 2020, Babeltrace 2 was released. Babeltrace 2 is a complete rewrite of the library, Python bindings, and CLI. It’s plugin-based and offers much more features and potential than Babeltrace 1 while delivering comparable performance. Some Linux distributions still provide packages for the Babeltrace 1 project. Both projects can coexist on the same system as there are no conflicting files. This README documents the Babeltrace 2 project.

Build Babeltrace 2.1 from source

Build-time requirements

To build Babeltrace 2.1, you need:

Compiler

• Any GCC-like compiler with C99 and GNU extension support.

  Clang is one of those.

• Any C++ compiler with C++17 support (for example, GCC ≥ 7.5 and Clang ≥ 5).

Tools

• GNU Make

• If you build from a Git clone:

  • GNU Automake ≥ 1.13

  • GNU Autoconf ≥ 2.69

  • GNU Libtool ≥ 2.2

  • flex ≥ 2.5.35

  • GNU Bison ≥ 3.0

Libraries

• A C library (for example, GNU C Library, musl libc)

• GLib ≥ 2.56 (Debian/Ubuntu: libglib2.0-dev; Fedora: glib2-devel)

• {fmt} ≥ 10.1.1 (Debian/Ubuntu: libfmt-dev; Fedora: fmt-devel)

  Use an in-tree {fmt} with --enable-vendor-fmt if you can’t install it.

If you need the bt2 Python bindings

• Python ≥ 3.6 (development libraries and python3-config) (Debian/Ubuntu: python3-dev; Fedora: python3-devel)

• SWIG ≥ 3.0

If you need the LTTng debug information filter component class (filter.lttng-utils.debug-info)

• elfutils ≥ 0.154 (Debian/Ubuntu: libelf-dev and libdw-dev; Fedora: elfutils-devel and elfutils-libelf-devel)

If you need the Babeltrace 2 C API HTML documentation

• Doxygen ≥ 1.8.6

If you need the Babeltrace 2 manual pages (only if you build from a Git clone)

• Asciidoctor ≥ 2.0.15

• xmlto ≥ 0.0.25

• The namespaced DocBook XSL stylesheets (often named docbook-xsl-ns).

If you need the bt2 Python bindings documentation

• Sphinx ≥ 1.3 for Python 3 (Debian/Ubuntu/Fedora: python3-sphinx)

If you need to build and run the tests

• Python ≥ 3.6 (development libraries and python3-config) (Debian/Ubuntu: python3-dev; Fedora: python3-devel)

• pytest ≥ 7.0.0 (Debian/Ubuntu/Fedora: python3-pytest)

  Use an in-tree pytest with --enable-vendor-pytest if you can’t install it.

• SWIG ≥ 3.0

• Catch2 ≥ 3.7.1 (Debian/Ubuntu: libcatch2-dev)

  Use an in-tree Catch2 v3 with --enable-vendor-catch2 if you can’t install it.

Disable test building with --disable-tests at configuration time.

Note	Thanks for the code! We’d like to thank the authors of the following projects which are embedded into the Babeltrace 2 source tree: Catch2 (with --enable-vendor-catch2) {fmt} (with --enable-vendor-fmt) JSON for Modern C++ span lite wise_enum zf_log

Procedure

To build Babeltrace 2:

1. If you build from a Git clone, do:

   $ ./bootstrap

   This generates the configure script and other important files.

2. Configure the project:

   $ ./configure

   The following options can modify the build:

   --disable-tests

   Do not build the tests at all.

   In that case, the check Make target still works, but it doesn’t run any test and exits with status 0.

   --enable-api-doc

   Build the Babeltrace 2 C API HTML documentation.

   --enable-built-in-plugins

   Statically link the official plugins into the babeltrace2 executable.

   --enable-built-in-python-plugin-support

   Statically link the Python plugin provider into libbabeltrace2.

   --enable-debug-info

   Build the LTTng debug information filter component class (filter.lttng-utils.debug-info).

   --enable-man-pages

   Build the Babeltrace 2 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 Babeltrace 2 Python plugins.

   --enable-vendor-pytest

   Use an in-tree pytest instead of an installed one.

   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 while developing the Babeltrace 2 project.

   BABELTRACE_DEV_MODE

   Set to 1 to enable the developer mode.

   The Babeltrace 2 developer mode enables more precondition and postcondition assertions to detect C API usage errors.

   BABELTRACE_MINIMAL_LOG_LEVEL

   Set the build-time, minimal logging level for all the modules of the project.

   Set to TRACE, DEBUG, or INFO.

   BABELTRACE_PLUGIN_PROVIDERS_DIR

   Installation directory of Babeltrace 2 plugin providers.

   BABELTRACE_PLUGINS_DIR

   Installation directory of Babeltrace 2 official plugins.

   Run ./configure --help to list all the available options and environment variables.

3. Build Babeltrace 2:

   $ make

To install Babeltrace 2:

• Run:

  # make install

Build Babeltrace 2 for plugin or application development

If you’re developing a Babeltrace 2 plugin or an application which uses libbabeltrace2, we recommend to:

• Build Babeltrace 2 from source in developer mode.

  The Babeltrace 2 developer mode enables more precondition and postcondition assertions to detect C API usage errors.

  The Babeltrace 2 C API documentation always lists the precondition and postconditions of functions.

  Set BABELTRACE_DEV_MODE=1 when you configure the Babeltrace 2 build.

• 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 configure the Babeltrace 2 build.

Babeltrace 2 development build configuration command line example:

$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure

Babeltrace 2 development build configuration with Python support example:

$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
  --enable-python-bindings --enable-python-plugins

See the Babeltrace 2 C API documentation for more information.

Use Babeltrace 2.1

See the Babeltrace 2 website to learn how to use the different parts of the project.

If you’re new to Babeltrace 2, make sure to read the babeltrace2-intro(7) manual page to familiarize yourself with the project.

Run-time requirements

Libraries

• A C library (for example, GNU C Library or musl libc)

• GLib ≥ 2.56 (Debian/Ubuntu: libglib2.0-0; Fedora: glib2)

If you need the bt2 Python bindings

• Python ≥ 3.6 (Debian/Ubuntu/Fedora: python3)

If you need the LTTng debug information filter component class (filter.lttng-utils.debug-info)

• elfutils ≥ 0.154 (Debian/Ubuntu: libelf and libdw; Fedora: elfutils-libs and elfutils-libelf)

Community

Babeltrace was born to parse CTF traces produced by LTTng 2.0 and to pretty-print their events.

Even though Babeltrace 2 is independent from the LTTng project today, their communities remain very close, which is why they share some communication channels and services:

Mailing list

lttng-dev (lttng-dev@lists.lttng.org)

IRC channel

#lttng on the OFTC network

Bug tracker

Babeltrace 2 bug tracker

GitHub project

efficios/babeltrace

Continuous integration

Babeltrace 2 jobs on the LTTng CI

Code review

Babeltrace 2 project on LTTng Review (Gerrit)