Skip to content

Latest commit

 

History

History
297 lines (226 loc) · 9.13 KB

README.adoc

File metadata and controls

297 lines (226 loc) · 9.13 KB
Raw

Babeltrace

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

babeltrace master build 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.

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
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 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
If you need the Babeltrace 2 manual pages

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