Babeltrace

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 versatile trace format produced by various tracers and tools such as LTTng and barectf. The Babeltrace 2 library and its Python bindings can read and write CTF traces.

See Babeltrace’s 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 2019, Babeltrace 2 was released. Babeltrace 2 is a complete rewrite of the library, Python bindings, and CLI. It is plugin-based and offers much more features and potential than Babeltrace 1 while showing comparable performance. Because Babeltrace 2 is still a young major release, some distributions still provide packages for the Babeltrace 1 project. Both projects can coexist on the same system as there are no common files. This file documents the Babeltrace 2 project.

Build Babeltrace 2.0 from source

Build-time requirements

To build Babeltrace 2.0, you need:

Compiler

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

  Clang is one of those.

Tools

• GNU Make

• If you build from a Git clone:

  • GNU Automake ≥ 1.10

  • GNU Autoconf ≥ 2.64

  • GNU Libtool ≥ 2.2

  • flex ≥ 2.5.35

  • GNU Bison ≥ 2.4

Libraries

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

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

If you need the bt2 Python bindings

• Python ≥ 3.4 (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 bt2 Python bindings documentation

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

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

If you need the Babeltrace 2 C API HTML documentation

• Doxygen ≥ 1.8.6

If you need the Babeltrace 2 manual pages

• Asciidoc ≥ 8.6.8

• xmlto ≥ 0.0.25

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:

   --enable-api-doc

   Build the Babeltrace 2 C API HTML documentation.

   --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.

   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 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 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 Babeltrace 2 plugin providers.

   BABELTRACE_PLUGINS_DIR

   Installation directory of Babeltrace 2 project plugins.

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

3. Build Babeltrace 2:

   $ make

To install Babeltrace 2:

• Do:

  # make install

Build Babeltrace 2 for plugin or application development

If you are developing a Babeltrace 2 plugin or an application which uses libbabeltrace2, we recommend that:

• You build Babeltrace 2 from source in developer mode.

  The Babeltrace 2 developer mode enables more precondition and postcondition assertions to detect programming errors.

  Set BABELTRACE_DEV_MODE=1 when you configure the Babeltrace 2 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 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.0

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

Run-time requirements

Libraries

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

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

If you need the bt2 Python bindings

• Python ≥ 3.4 (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

Note	Babeltrace was born to parse CTF traces produced by LTTng 2.0 and pretty-print their events. Even though Babeltrace is independant 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 bug tracker

GitHub project

efficios/babeltrace

Continuous integration

Babeltrace’s master build on LTTng’s CI

Code review

babeltrace project on LTTng Review