BABELTRACE2-INTRO(7)

📦
version 2.1.2 · 6 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 BABELTRACE2-INTRO(7) 💖

from the Babeltrace 2 manual 🫶 bestie, this is the intro page and it’s lowkey a whole vibe.

✨ NAME ✨

babeltrace2-intro — Introduction to Babeltrace 2

🌸 DESCRIPTION 🌸

okay so this manual page is literally an introduction to the Babeltrace 2 project. no cap.

The “WHAT IS BABELTRACE 2?” section describes the parts of the project and shows the major changes from Babeltrace 1 to Babeltrace 2 while the “BABELTRACE 2 CONCEPTS” section defines the core concepts of Babeltrace 2.

The “TRACE PROCESSING GRAPH REPRESENTATION” section shows how some concepts are visually represented in other Babeltrace 2 manual pages.

🔥 WHAT IS BABELTRACE 2? 🔥

Babeltrace 2 is an open-source software project of which the purpose is to process or convert traces (see <https://en.wikipedia.org/wiki/Tracing_(software)>). it’s giving trace whisperer.

The Babeltrace 2 project includes the following parts:

  • Babeltrace 2 library (libbabeltrace2) — a shared library with a C API. main character energy fr.

With libbabeltrace2, you can programmatically create plugins and component classes, build and run trace processing graphs, and more (see the “BABELTRACE 2 CONCEPTS” section for more details about those concepts).

All the other Babeltrace 2 parts rely on this library. periodt.

  • babeltrace2 command-line program — a command-line interface which uses libbabeltrace2 to load plugins, create a trace processing graph, create components, connect their ports correctly, and run the graph.

You can also use babeltrace2 to list the available plugins or to query an object from a component class.

See babeltrace2(1).

  • Babeltrace 2 Python bindings — a Python 3 package (bt2) which offers a Pythonic interface of libbabeltrace2.

You can perform the same operations which are available in libbabeltrace2 with the Python bindings, but more conveniently and with less code. However, the Python bindings are less performant than libbabeltrace2. so it’s cute and convenient but not the fastest, ngl.

  • Babeltrace 2 project plugins — the Babeltrace 2 plugins shipped with the project.

Those plugins aren’t special in that they only rely on libbabeltrace2 and you don’t need them to use libbabeltrace2, babeltrace2(1), or the Python bindings. However, the project plugins provide many widely used trace format encoders/decoders as well as common trace processing graph utilities.

The Babeltrace 2 project plugins are:

See babeltrace2-plugin-ctf(7).

See babeltrace2-plugin-lttng-utils(7).

  • text — Plain text input/output.

See babeltrace2-plugin-text(7).

  • utils — Common graph utilities (muxer, trimmer, counter, dummy sink).

See babeltrace2-plugin-utils(7).

✨ Changes since Babeltrace 1 ✨

This manual page is an introduction to Babeltrace 2, a rewrite of Babeltrace 1 with a focus on extensibility, flexibility, and interoperability. it’s the glow-up era.

Babeltrace 1 exists since 2010.

You can install both projects on the same file system as there are no file name conflicts. so they can coexist, iconic.

The major improvements brought by Babeltrace 2 are:

🌈 General

  • Full plugin support: any user can distribute a Babeltrace 2 plugin and, as long as libbabeltrace2 finds it, any application linked to libbabeltrace2 can load it and use it.

Plugins aren’t just trace format encoders and decoders: they package source, filter, and sink component classes so that you can connect specialized, reusable components together in a trace processing graph to create a customized trace conversion or analysis device.

This modular strategy is much like how the FFmpeg (see <https://www.ffmpeg.org/>), GStreamer (see <https://gstreamer.freedesktop.org/>), and DirectShow (see <https://en.wikipedia.org/wiki/DirectShow>) projects approach media stream processing. iykyk.

  • All the parts of the Babeltrace 2 project run on the major operating systems, including Windows and macOS. cross-platform slay.
  • Some component classes, such as sink.text.pretty (similar to the text output format of babeltrace(1)) and sink.text.details, can write color codes to the standard output when it’s connected to a color-enabled terminal.

The Babeltrace 2 log, printed to the standard output, can also be colorized.

💻 Command-line interface

  • Whereas you can convert traces from one format to another with the Babeltrace 1 CLI tool, babeltrace(1), you can also execute a custom trace manipulation task with babeltrace2(1) thanks to the babeltrace2-run(1) command. so you’re not just converting, you’re customizing.
  • The babeltrace2-convert(1) command features an automatic source component discovery algorithm to find the best suited components to create for a given non-option argument (file or directory path, or custom string like an LTTng live (see <https://lttng.org>) URL).

For example:

$ babeltrace2 /path/to/ctf/trace

$ babeltrace2 net://localhost/host/myhost/my-session

🧚 CTF (see <https://diamon.org/ctf/>) 1.8 and 2 input/output

  • The source.ctf.fs component class, which is more or less the equivalent of the Babeltrace 1 ctf input format, has features not found in Babeltrace 1:
    • The component handles many trace quirks which are the results of known tracer bugs and corner cases (LTTng-UST, LTTng-modules, and barectf (see <https://github.com/efficios/barectf>)), making it possible to decode malformed packets. messy traces? handled.
    • The component merges CTF traces sharing the same identity into a single, logical trace.

This feature supports LTTng 2.11’s tracing session rotation trace chunks.

  • With a sink.ctf.fs component, you can create CTF traces on the file system.

With babeltrace2(1), you can use the --output-format=ctf and --output options to create an implicit sink.ctf.fs component. sneaky but useful.

For example:

$ babeltrace2 /path/to/input/trace \
              --output-format=ctf --output=trace-dir

🔥 LTTng live (see <https://lttng.org>) input

  • The babeltrace(1) command exits successfully when it cannot find an LTTng live (--input-format=lttng-live option) tracing session. not me being chill about missing sessions.

The session-not-found-action initialization parameter controls what a source.ctf.lttng-live message iterator does when it cannot find the remote tracing session.

If the action is end, then the message iterator does like babeltrace(1) and simply ends successfully.

If the action is continue (the default), then the message iterator never ends: it keeps on trying until the tracing session exists, indeed subscribing to the session. persistent queen.

👑 Library

  • libbabeltrace2 shares nothing with libbabeltrace. zero overlap.

The Babeltrace 2 library C API has features such as:

  • A single header file.
  • Function precondition and postcondition checking.
  • Object-oriented model with shared and unique objects.
  • Strict C typing and const correctness.
  • User-extensible classes.
  • Rich, thread-safe error reporting.
  • Per-component and per-subsystem logging levels.
  • Trace intermediate representation (IR) objects to make the API trace-format-agnostic.
  • A versioned protocol for message interchange between components to enable forward and backward compatibility.
  • You can build the library in developer mode to enable an extensive set of function precondition and postcondition checks.

The developer mode can help detect programming errors early when you develop a Babeltrace 2 plugin or an application using libbabeltrace2.

See the project README for build-time requirements and detailed build instructions.

✨ BABELTRACE 2 CONCEPTS ✨

okay bestie, this is the section where we define the main concepts of the Babeltrace 2 project. fr fr.

These concepts translate into types and functions in libbabeltrace2 and its Python bindings, but also as command-line actions and options in the babeltrace2 program. The other Babeltrace 2 manual pages assume that you are familiar with the following definitions. 💅

Some Babeltrace 2 concepts are interdependent: it's totally normal to jump from one definition to another to understand the big picture. it's giving spiderweb, and we love that for us 🕸️✨

🧩 Component class

A reusable class which you can instantiate as one or more components within a trace processing graph.

There are three types of component classes used to create the three types of components: source, filter, and sink.

A component class implements methods, one of which is an initialization method, or constructor, to create a component. You pass initialization parameters to this method to customize the created component. For example, the initialization method of the source.ctf.fs component class accepts a mandatory inputs parameter which is an array of file system path(s) to the CTF trace(s). It also accepts an optional clock-class-offset-ns parameter which is an offset, in nanoseconds, to add to all the clock classes (descriptors of stream clocks) found in the metadata stream of the traces. 👑

A component class can have a description and a help text.

🎀 Component

A node within a trace processing graph.

There are three types of components:

🌸 Source component

An input component which produces messages.

Examples: CTF files input, log file input, LTTng live input, random event generator. 🎲

🌸 Filter component

An intermediate component which can transform the messages it consumes, augment them, sort them, discard them, or create new ones. multitasking queen 💅

Examples: filter which removes messages based on an expression, filter which adds debugging information to selected events, message muxer, trace trimmer.

🌸 Sink component

An output component which consumes messages and usually writes them to one or more formatted files.

Examples: log file output, CTF files output, pretty-printed plain text output.

Components are connected together within a trace processing graph through their ports. Source components have output ports, sink components have input ports, and filter components have both. 😌

A component is the instance of a component class. The terms component and component class instance are equivalent. no cap.

Within a trace processing graph, each component has a unique name. This isn't the name of its component class, but an instance name. If human is a component class name, then Nancy and John could be component names. 🫶 iconic honestly.

Once a graph is configured (the first time it runs), you cannot add components to it for the remaining graph lifetime. that's just the rules bestie 😭

🔌 Port

A connection point, on a component, from which are sent or where are received messages when the trace processing graph runs.

An output port is from where messages are sent. An input port is where messages are received. Source components have output ports, sink components have input ports, and filter components have both. (yes we said this already, it's that important 💖)

You can only connect an output port to a single input port. monogamy but make it dataflow 🦋

All ports don't need to be connected. ✨

A filter or sink component receiving messages from its input ports is said to consume messages.

The link between an output port and input port is a connection.

Once a graph is configured (the first time it runs), you cannot connect ports for the remaining graph lifetime. 🫠

🔗 Connection

The link between an output port and an input port through which messages flow when a trace processing graph runs. it's giving ✨ situationship ✨ except the messages actually flow.

🔁 Message iterator

An iterator on an input port of which the returned elements are messages.

A component or another message iterator can create many message iterators on a single input port, before or while the trace processing graph runs. slay.

💌 Message

The element of a message iterator.

Messages flow from output ports to input ports.

A source component message iterator produces messages, while a sink component consumes them. A filter component message iterator can both consume and produce messages. balanced. 👑

The main types of messages are:

🌟 Event

A trace event record within a packet or within a stream.

🌟 Packet beginning

The beginning of a packet within a stream.

A packet is a conceptual container of events. 📦

🌟 Packet end

The end of a packet within a stream.

🌟 Stream beginning

The beginning of a stream.

A stream is a conceptual container of packets and/or events. 🌊

Usually, a given source component output port sends packet and event messages which belong to a single stream, but it's not required. rules are more like guidelines 💅

🌟 Stream end

The end of a stream.

🌟 Discarded events

A count of discarded events within a given time interval for a given stream. 😭 gone but not forgotten.

🌟 Discarded packets

A count of discarded packets within a given time interval for a given stream.

The Message Interchange Protocol (MIP) dictates the expected types, order, and contents of messages. When you create a trace processing graph, you specify a MIP version, and all the components of said graph must comply with the selected protocol. This feature is what makes forward and backward compatibility possible when a Babeltrace 2 release changes the libbabeltrace2 API. ate. 🔥

🕸️ Trace processing graph

A filter graph (see https://en.wikipedia.org/wiki/Filter_graph) where nodes are components and messages flow from output ports to input ports.

You can build a trace processing graph with libbabeltrace2, with the Babeltrace 2 Python bindings, or with the babeltrace2-run(1) and babeltrace2-convert(1) CLI commands. ✨

When a trace processing graph runs, the sink components consume messages from their input ports, making all the graph message iterators work one message at a time to perform the trace conversion or analysis duty. it's giving conveyor belt but make it ✨ elegant ✨

📦 Plugin

A container, or package, of component classes as a shared library or Python module.

Each component class within a plugin has a type (source, filter, or sink) and a name. The type and name pair is unique within a given plugin.

libbabeltrace2 can load a plugin (.so, .dll, or .py file) at run time: the result is a plugin object in which you can find a specific component class and instantiate it within a trace processing graph as a component. 🧚

The babeltrace2 program uses the COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME format to identify a specific component class within a specific plugin. COMP-CLS-TYPE is either source (or src), filter (or flt), or sink. 💅

You can list the available Babeltrace 2 plugins with the babeltrace2-list-plugins(1) command. go look bestie 👀

🔍 Query

An operation with which you can get a named object from a component class, possibly with custom query parameters.

The plain text metadata stream of a CTF trace and the available LTTng live sessions of a given LTTng relay daemon are examples of query objects. 🌈

You can use libbabeltrace2, the Babeltrace 2 Python bindings, or the babeltrace2-query(1) CLI command to query a component class object. ✨

🎀 TRACE PROCESSING GRAPH REPRESENTATION 🎀

ok bestie, this is the part where it all becomes visual. 💅 In these manual pages, we draw a component as a lil box, okay?

The box has, at the top: the component class type, the plugin name, and the component class name. Just below that, tucked between square brackets, you get its component name inside the trace processing graph. ✨

And the ports? Each one is an @ symbol sitting on the border of the component box, with its name written inside the box. Output ports live on the right border, input ports live on the left border. That's it, that's the whole system. 🫶

So like, here's a source component box:

    +------------+
    | src.ctf.fs |
    |  [my-src]  |
    |            |
    |    stream0 @
    |    stream1 @
    |    stream2 @
    +------------+

This one is an instance of the source.ctf.fs component class, and its name is my-src. It has three output ports: stream0, stream1, and stream2. no cap. 🌸

A trace processing graph is just a bunch of these component boxes connected together, and the connections are arrows going from output ports to input ports. iconic behaviour honestly. 🔥

Here's a simple conversion graph for you:

    +------------+    +-----------------+    +------------------+
    | src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
    |    [ctf]   |    |     [muxer]     |    |      [text]      |
    |            |    |                 |    |                  |
    |    stream0 @--->@ in0         out @--->@ in               |
    |    stream1 @--->@ in1             |    +------------------+
    |    stream2 @--->@ in2             |
    +------------+    @ in3             |
                      +-----------------+
👀 tiny detail, don't skip it: input port in3 of the component muxer isn't connected in this example. It's just... sitting there. living its truth. 💀

Sometimes we symbolically draw other resources too — the stuff that gets consumed by or produced by components. In that case we still use arrows, but they don't touch port symbols (@) — with one exception: messages. 😌

So in the graph above: the ctf source component consumes a CTF trace, and the text sink component prints plain text to the terminal. Which means the fuller diagram looks like this:

    CTF trace
      |
      |   +------------+    +-----------------+    +------------------+
      |   | src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
      '-->|    [ctf]   |    |     [muxer]     |    |      [text]      |
          |            |    |                 |    |                  |
          |    stream0 @--->@ in0         out @--->@ in               |
          |    stream1 @--->@ in1             |    +-----+------------+
          |    stream2 @--->@ in2             |          |
          +------------+    @ in3             |          '--> Terminal
                            +-----------------+

see how the CTF trace and the Terminal are just floating out there with arrows and no @? yeah. that's the vibe. 💖

And here's one more, a more complex graph that splits a specific stream using some criteria:

    +------------+    +-----------------+    +------------------+
    | src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
    |  [ctf-in]  |    |     [muxer]     |    |      [text]      |
    |            |    |                 |    |                  |
    |    stream0 @--->@ in0         out @--->@ in               |
    |    stream1 @--->@ in1             |    +------------------+
    |    stream2 @-.  @ in2             |
    +------------+ |  +-----------------+      +-------------+
                   |                           | sink.ctf.fs |
                   |                           |  [ctf-out0] |
                   |  +-------------------+    |             |
                   |  | flt.some.splitter | .->@ in          |
                   |  |     [splitter]    | |  +-------------+
                   |  |                   | |
                   '->@ in              A @-'  +-------------+
                      |                 B @-.  | sink.ctf.fs |
                      +-------------------+ |  |  [ctf-out1] |
                                            |  |             |
                                            '->@ in          |
                                               +-------------+

okay the way that little splitter box has two output ports and one input port and feeds two different sinks... that's giving main character energy fr fr. 👑

🐛 BUGS 🐛

If you hit any issue or usability problem, please report it on the Babeltrace bug tracker (see <https://bugs.lttng.org/projects/babeltrace>). bestie we want to know, we're not gonna be weird about it, promise. 🙈

💬 RESOURCES 💬

The Babeltrace project shares some communication channels with the LTTng project (see <https://lttng.org/>).

👑 AUTHORS 👑

The Babeltrace 2 project is the result of hard work by many regular developers and occasional contributors. genuinely, so many people, so much effort, we love to see it. 💜

The current project maintainer is Jérémie Galarneau <mailto:jeremie.galarneau@efficios.com>.

This manual page is part of the Babeltrace 2 project.

Babeltrace is distributed under the MIT license (see <https://opensource.org/licenses/MIT>).

🔗 SEE ALSO 🔗

and that's a wrap on the whole intro page, bestie!! 🦋 this was Babeltrace 2.1.2, dated 10 January 2025, from the BABELTRACE2-INTRO(7) manual. go forth and build graphs, you absolute legend. 💅✨🎀

📦 where this page comes from