Welcome to the Babeltrace 2 Python 3 bindings documentation (version 2.0).


This documentation (text and illustrations) is licensed under a Creative Commons Attribution-ShareAlike 4.0 International license.


This documentation is incomplete.

In the meantime:

  • See Examples to learn how to accomplish common tasks.

  • Have a look at the Babeltrace 2 C API documentation.

    The Babeltrace 2 Python bindings wrap all the functionalities of libbabeltrace2 in a reasonably systematic manner.


What’s Babeltrace 2?

Babeltrace 2 is an open-source software project by EfficiOS; its purpose is to process or convert traces.

The Babeltrace 2 project contains:

  • A library, libbabeltrace2, which all the other parts rely on.

    libbabeltrace2 offers a C99 interface.

  • A command-line program, babeltrace2(1), which can convert and manipulate traces.

  • Python 3 bindings which offer a Pythonic interface of libbabeltrace2.

    This documentation is about those bindings.

  • “Standard” plugins which ship with the project.

    Common Trace Format (CTF) input and output, plain text input and output, and various utilities are part of those plugins.

With the Babeltrace 2 Python bindings, you can write programs to do everything you can do, and more, with libbabeltrace2, that is:

  • Write custom source, filter, and sink component classes which you can package as Python plugins.

    Component classes are instantiated as components within a trace processing graph and are assembled to accomplish a trace manipulation or conversion job.

  • Load plugins (compiled shared object or Python modules), instantiate their component classes within a trace processing graph, connect the components as needed, and run the graph to accomplish a trace manipulation or conversion job.

    This is what the babeltrace2 CLI tool’s convert and run commands do, for example.

A trace processing graph contains connected components. The specific component topology determines the trace processing task to realize.


A conversion graph, a specific trace processing graph.

Between the components of a trace processing graph, messages flow from output ports to input ports following the configured connections through message iterators. There are many types of messages, chief amongst which is the event message.

With the Babeltrace 2 Python bindings, you can also query some specific object from a component class (for example, the available LTTng live sessions of an LTTng relay daemon). This is what the babeltrace2 CLI tool’s query command does, for example.

Make sure to read the babeltrace2-intro(7) manual page to learn even more about the Babeltrace 2 project and its core concepts.