Skip to content

Babeltrace /ˈbæbəltreɪs/ is an open-source trace manipulation toolkit.

License

Notifications You must be signed in to change notification settings

efficios/babeltrace

Repository files navigation

Babeltrace 2

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

babeltrace master linuxbuild babeltrace

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.

A basic Babeltrace 2 conversion graph

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

  • Any C++ compiler with C++11 support (for example, GCC ≥ 4.8 and Clang ≥ 3.3).

Tools
Libraries
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 Babeltrace 2 C API HTML documentation
If you need the Babeltrace 2 manual pages
If you need the bt2 Python bindings documentation
  • Sphinx ≥ 1.3 for Python 3 (Debian/Ubuntu/Fedora: python3-sphinx)

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:

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-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 the babeltrace2 executable.

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

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

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

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)