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

Welcome to the Babeltrace 2 C API (libbabeltrace2) documentation!

To get an idea of how to use the libbabeltrace2 API, have a look at the guides and examples. That being said, we recommend that you read the API fundamentals to understand what the API expects exactly.

If you are developing a Babeltrace 2 plugin or an application which uses libbabeltrace2, we recommend that you build the Babeltrace 2 library for development.

Babeltrace 2 in a nutshell

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.

This documentation is about libbabeltrace2's API.
A command-line program, babeltrace2, which can convert and manipulate traces.
Python 3 bindings which offer a Pythonic interface of libbabeltrace2.
"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 library, you can:

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

Component classes are instantiated as components within a trace processing graph and components are assembled to accomplish a trace manipulation or conversion job.
Load plugins, 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 libbabeltrace2, 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 babeltrace2-intro(7) to learn even more about the Babeltrace 2 project and its core concepts.

What's in this documentation?

API fundamentals

Explains the basic principles of the Babeltrace 2 C API.

Make sure you understand this section as you need this knowledge to use the API correctly.

Guides

Shows how to achieve common tasks with libbabeltrace2.

Guides help you navigate through the most important features of the library and its API.

Examples

Contains simple and more complex examples which apply the different parts of the API to accomplish real tasks.

API reference

Documents all the Babeltrace 2 C functions, definitions, macros, enumerators, and types.

Each documentation module describes its API thoroughly and how it's related to other modules.