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)>).
The Babeltrace 2 project includes the following parts:
Babeltrace 2 library (libbabeltrace2)
A shared library with a C API.
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.
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.
Babeltrace 2 project's plugins
The Babeltrace 2 plugins shipped with the project.
Those plugins are not 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's plugins provide many widely used trace format
encoders/decoders as well as common trace processing graph
utilities.
The Babeltrace 2 project's plugins are:
ctf
Common Trace Format (see <https://diamon.org/ctf/>) (CTF)
input/output, including the LTTng live source.
See babeltrace2-plugin-ctf(7).
lttng-utils
Graph utilities specific to LTTng (see
<https://lttng.org/>) traces.
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.
Babeltrace 1 exists since 2010.
You can install both projects on the same file system as there
are no file name conflicts.
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 are not 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.
• All the parts of the Babeltrace 2 project run on the
major operating systems, including Windows and macOS.
• 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 Babeltrace 1's CLI tool, babeltrace(1), you can also
execute a custom trace manipulation task with
babeltrace2(1) thanks to the babeltrace2-run(1) command.
• 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/>) input/output
• The source.ctf.fs component class, which is more or less
the equivalent of Babeltrace 1's 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.
• The component merges CTF traces sharing the same UUID
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.
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.
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, the message iterator does like
babeltrace(1) and simply ends successfully.
If the action is continue (the default), the message
iterator never ends: it keeps on trying until the tracing
session exists, indeed subscribing to the session.
Library
• libbabeltrace2 shares nothing with libbabeltrace.
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's README for build-time requirements and
detailed build instructions.
