Hi everyone! We’re very excited to announce the first Babeltrace 2.0 release candidate! 😃
What’s new since Babeltrace 2.0.0-pre5?
Babeltrace 2.0.0-pre5 was released 3 May 2019.
We also updated all the Babeltrace 2 manual pages.
The build-time and run-time requirements for Babeltrace 2.0.0-rc1 are updated:
Babeltrace 2.0.0-rc1 does not need the popt library anymore to parse command-line arguments.
We wrote our own command-line argument parser to remove this obsolete requirement and to support advanced, position-dependent parsing.
Babeltrace 2.0.0-rc1 requires GLib ≥ 2.28 at build time and run time instead of the previous ≥ 2.22 requirement.
Automatic source component discovery
command’s new automatic source component discovery feature, specify
a path, URI, or arbitrary string to let
babeltrace2 find the most
appropriate components to use:
$ babeltrace2 /path/to/ctf/trace $ babeltrace2 net://localhost/host/myhost/my-session
This means you don’t need to create an explicit component with the
option most of the time.
Behind the scenes, this feature queries the
object from all known component classes: a component class can reply
with a confidence score to indicate its ability to handle a given path
or custom string.
Source component classes do not have to implement the
If a component class does not implement
this query, the automatic source component discovery algorithm won’t
consider it. In that case, you must instantiate such a component class
explicitly with the
sink.text.details component class
This new component pretty-prints all the details of the messages it consumes.
The output is optimized to be human-readable, yet it is deterministic for testing and debugging purposes.
You can use a
sink.text.details component to easily inspect messages
flowing at any point of a graph and make it easy to test and
troubleshoot other component classes.
The Babeltrace 2 project uses this component class for many tests.
For example, a
source.ctf.fs component can now read data streams which
lttng-crash tool generates,
even if the last packets can be malformed.
section of the
babeltrace2-source.ctf.fs(7) manual page for more
Library and Python bindings
Library-specific: simple sink component
Add a sink component to a graph easily using the new simple sink component C API.
A simple sink component is a sink component with a single input port and a single message iterator.
This interface reduces the amount of code you need to write to create a basic Babeltrace 2 message consumer.
Just provide a consumption user function which receives the component’s message iterator to consume upstream messages.
You can also implement other user functions:
- Initialization function
Called once during the initialization phase of the graph.
- Finalization function
Called once during the finalization phase of the graph.
Python-specific: automatic source component discovery using
bt2.TraceCollectionMessageIterator object, your application can
access additional component classes installed on the system from the get
New field class types
New field classes are available in libbabeltrace2 and its Python bindings to support eventual, new CTF 2 field classes.
The new fields are:
Contains a boolean value.
- Bit array
Contains a fixed-size array of bits.
A bit array field can represent a CPU status or flag register value, for example.
Unlike integer fields, a bit array field is not a numerical field.
Contains an optional field.
An option field class is conceptually equivalent to a variant field class with two options: no field class and the optional field class.
Attach custom user attributes to any of the following trace IR objects:
This new property exists because we expect the CTF 2 metadata objects to contain user attributes too.
Report rich error causes from user functions with the new thread-safe error reporting API.
The error reporting API makes it possible for the various actors interacting through libbabeltrace2 to precisely describe the chain of events that lead to a given error. As a library user, you can access this list of causes and reduce the time needed to troubleshoot problems.
This feature is similar to the stack trace which exception objects contain in many programming languages.
When an error occurs, the
uses this error reporting API to show the top-level error itself, but
also a detailed list of its causes, for example:
ERROR: [Babeltrace CLI] (babeltrace2.c:2546) Graph failed to complete successfully CAUSED BY [Babeltrace library] (graph.c:604) Component's "consume" method failed: ..., comp-name="sink.text.details", ... CAUSED BY [Babeltrace library] (iterator.c:889) Component input port message iterator's "next" method failed: ..., iter-upstream-comp-class-name="debug-info", ... CAUSED BY [Babeltrace library] (iterator.c:889) Component input port message iterator's "next" method failed: ..., iter-upstream-comp-name="muxer", ... CAUSED BY [Babeltrace library] (iterator.c:889) Component input port message iterator's "next" method failed: ..., iter-upstream-comp-class-name="MyFirstSource", ... CAUSED BY [src.demo.MyFirstSource (some-name): 'source.demo.MyFirstSource'] (bt2/native_bt_log_and_append_error.h:100) Traceback (most recent call last): File "/usr/local/lib/python3.6/dist-packages/bt2/message_iterator.py", line 151, in _bt_next_from_native msg = next(self) File "./bt_plugin_foo.py", line 33, in __next__ raise Exception Exception
In the Python bindings, raise any exception object as usual from a user
bt2 package converts it to a libbabeltrace2 error cause
for other parties.
Coinstallation with Babeltrace 1
To make the transition from Babeltrace 1 to Babeltrace 2 easier, we decided to make both projects coinstallable thanks to those changes:
The Babeltrace 2 CLI tool is named
The Babeltrace 2 library’s include directory is named
The Babeltrace 2 library is named
The Babeltrace 2 manual page names start with
Distribution packages will be available for both Babeltrace 1 and Babeltrace 2.
Message Interchange Protocol versioning
Future-proof component classes using Message Interchange Protocol versioning.
As Babeltrace 2 evolves, we expect to introduce new concepts and objects to libbabeltrace2 such as field class types, message types, methods, and message ordering requirements. To ensure forward and backward compatibility can be maintained across future releases of Babeltrace 2, Babeltrace 2.0.0-rc1 adds the concept of Message Interchange Protocol (MIP).
Should we introduce a breaking change to the protocol which trace processing graph components must honor, we’ll bump the MIP version to announce the modified interface.
You can consider the MIP version as an implicit precondition variable for almost all the libbabeltrace2 functions.
Given the expected initialization parameters, a component class can report a range of supported MIP versions. You can then build a graph which operates with a specific MIP version to ensure all its components exchange messages using the same protocol.
The Babeltrace 2 C API uses the
const qualifier liberally to catch
many programming errors at compile time.
As the Python language does not have a
const feature to express
immutability constraints, the Python classes are now split into constant
and mutable variants. Mutable variants of the classes have methods to
modify and read object properties whereas their constant counterpart
only have reading methods.
All constant classes end with
If you try to modify a constant object, Python raises an attribute error.
Optional packet support
The Babeltrace 2 packet concept exists because CTF needs it. However, many trace formats don’t.
With Babeltrace 2.0.0-rc1, you don’t need to create packet objects to conceptually contain event objects. As such, you don’t need to emit packet beginning and end messages.
By default, packets are not supported for a given stream class: you need to explicitly enable their support.
TRACE logging level
The VERBOSE logging level is now the TRACE logging level.
It’s not obvious whether the VERBOSE level is more or less verbose than the DEBUG level. With TRACE instead, it becomes evident.
Manual pages are finalized and reflect the changes introduced in Babeltrace 2.0.0-rc1.
- Standard query objects
- CTF input/output plugin
- LTTng-specific utilities plugin
- General utilities plugin
- Plain text input/output plugin
What’s new since Babeltrace 1.5?
This section presents a very high level view of the changes from Babeltrace 1.5 to Babeltrace 2.
to learn more about the Babeltrace 2 project and its core concepts.
Trace processing graph
Connect components within a trace processing graph and run it to execute trace manipulation or conversion tasks.
Components are instances of component classes. Babeltrace 2 plugins (shared libraries or Python files) are distributable packages of component classes.
- CTF file system source
Read CTF traces from the file system.
- LTTng live source
Connect to an LTTng relay daemon and receive CTF streams.
- CTF file system sink
Write CTF traces to the file system.
- Debugging information filter for LTTng traces
Augment compatible events with debugging information.
- Linux kernel ring buffer source
Read Linux ring buffer lines (
dmesg(1)output) from a file or from standard input.
- Detailed sink
Print messages with details.
- Pretty-printing sink
Pretty-print messages (
textformat of Babeltrace 1).
- Message muxer filter
Sort messages from multiple input ports to a single output port by time.
- Message trimmer filter
Discard messages that occur outside a specific time range.
- Message counter sink
Count messages and print the statistics.
- Dummy sink
Consume messages and discard them.
Read multiple CTF traces sharing the same UUID
Merge multiple physical traces sharing the same UUID to a single logical trace.
This is especially useful to read traces produced by the tracing session rotation feature introduced in LTTng 2.11.
Verify your custom component classes by building and running Babeltrace 2 in developer mode.
This special operation mode enables a large number of libbabeltrace2 function precondition and postcondition checks. This is at the cost of making the library less efficient.
With the developer mode, you can develop and test new plugins while ensuring that they honour the contract of the various libbabeltrace2 functions you use.
Since we assume that component classes have been tested in developer mode by their authors, the release, or production build configuration of Babeltrace 2 does not check fast path preconditions and postconditions at run time, resulting in improved performance.
To build Babeltrace 2 in developer mode and test your own plugins, set the
BABELTRACE_DEV_MODE environment variable to
1 at configuration time:
$ BABELTRACE_DEV_MODE=1 ./configure
When a function precondition or postcondition is not satisfied,
libbabeltrace2 prints why and details to the standard error and calls
abort(), just like
assert(), so that you can inspect the programming
error’s context with a debugger.
10-06 09:12:20.228 62362 62362 F LIB/VALUE firstname.lastname@example.org:887 Babeltrace 2 library precondition not satisfied; error is: 10-06 09:12:20.228 62362 62362 F LIB/VALUE email@example.com:887 Value object is NULL: 10-06 09:12:20.228 62362 62362 F LIB/VALUE firstname.lastname@example.org:887 Aborting...
The Babeltrace CLI and some components now use colors when the connected terminal supports it.
LTTng live source’s subscribe mode
Subscribe to a tracing session served by an LTTng
relay daemon with a
source.ctf.lttng-live component in subscribe
To subscribe to a session, set the
initialization parameter to
continue. In subscribe mode, the source
attempts to consume an LTTng relay daemon’s tracing session and
attempts to reconnect periodically if it does not find the target
To use the
continue action explicitly, do:
$ babeltrace2 net://relayhost/host/tgthost/my-session \ --params='session-not-found-action="continue"'
The libbabeltrace2 API shares nothing with Babeltrace 1’s libbabeltrace API.
The libbabeltrace2 API is trace-format agnostic and aims at making it easy to correctly manipulate traces and logs produced in a variety of formats.
Babeltrace 2 still provides Python bindings through the
bt2 package, exposing
all the features of the C API. The
bt2 package is not a drop-in
replacement of the Babeltrace 1’s
As we enter the release candidate phase of Babeltrace 2’s development cycle, we are hard at work putting the finishing touches on our way to the final 2.0.0 release.
We are currently documenting the entire Babeltrace 2 C API to make the development of new component classes as easy as possible.
We’ll also work on the Python bindings documentation.
The documentation of the API will be made available on the official Babeltrace website.
Improve test coverage.
Improve resilience to corrupted/malformed CTF traces.
Minor internal cleanups and bug fixes.