|BABELTRACE2-INTRO(7)||Babeltrace 2 manual||BABELTRACE2-INTRO(7)|
babeltrace2-intro - Introduction to Babeltrace 2
This manual page is an introduction to the Babeltrace 2 project.
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)>).
The Babeltrace 2 project includes the following parts:
Babeltrace 2 library (libbabeltrace2)
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
You can also use babeltrace2 to list the available plugins or to query an object from a component class.
Babeltrace 2 Python bindings
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
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:
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:
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.
The Babeltrace 2 log, printed to the standard output, can also be colorized.
$ babeltrace2 /path/to/ctf/trace
$ babeltrace2 net://localhost/host/myhost/my-session
CTF (see <https://diamon.org/ctf/>) input/output
This feature supports LTTng 2.11’s tracing session rotation trace chunks.
With babeltrace2(1), you can use the --output-format=ctf and --output options to create an implicit sink.ctf.fs component.
$ babeltrace2 /path/to/input/trace \
LTTng live (see <https://lttng.org>) input
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.
The Babeltrace 2 library C API has features such as:
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.
BABELTRACE 2 CONCEPTS¶
This section defines the main concepts of the Babeltrace 2 project.
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 is normal to jump from one definition to another to understand the big picture.
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 traces’s metadata.
A component class can have a description and a help text.
There are three types of components:
Examples: CTF files input, log file input, LTTng live input, random event generator.
Examples: filter which removes messages based on an expression, filter which adds debugging information to selected events, message muxer, trace trimmer.
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.
Within a trace processing graph, each component has a unique name. This is not the name of its component class, but an instance name. If human is a component class name, than Nancy and John could be component names.
Once a graph is configured (the first time it runs), you cannot add components to it for the remaining graph’s lifetime.
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.
You can only connect an output port to a single input port.
All ports do not 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’s lifetime.
A component or another message iterator can create many message iterators on a single input port, before or while the trace processing graph runs.
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.
The main types of messages are:
A packet is a conceptual container of events.
A stream is a conceptual container of packets and/or events.
Usually, a given source component’s output port sends packet and event messages which belong to a single stream, but it’s not required.
Trace processing graph
When a trace processing graph runs, the sink components consume messages from their input ports, making all the graph’s message iterators work one message at a time to perform the trace conversion or analysis duty.
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.
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’s object.
TRACE PROCESSING GRAPH REPRESENTATION¶
In the Babeltrace 2 manual pages, a component is represented with a box. The box has the component class type, plugin name, and component class name at the top. Just below, between square brackets, is its component name within the trace processing graph. Each port is represented with an @ symbol on the border(s) of the component box with its name inside the box. Output ports are on the box’s right border while input ports are on the box’s left border.
For example, 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 named my-src. It has three output ports named stream0, stream1, and stream2.
A trace processing graph is represented with multiple component boxes connected together. The connections are arrows from output ports to input ports.
For example, here’s a simple conversion graph:
+------------+ +-----------------+ +------------------+ | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty | | [ctf] | | [muxer] | | [text] | | | | | | | | stream0 @--->@ in0 out @--->@ in | | stream1 @--->@ in1 | +------------------+ | stream2 @--->@ in2 | +------------+ @ in3 |
Note that input port in3 of component muxer is not connected in this example.
Sometimes, we symbolically represent other resources which are consumed from or produced by components. In this case, arrows are used, but they do not go to or from port symbols (@), except for messages. For example, in the graph above, the ctf source component consumes a CTF trace and the text sink component prints plain text to the terminal, so here’s a more complete diagram:
| +------------+ +-----------------+ +------------------+
| | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
'-->| [ctf] | | [muxer] | | [text] |
| | | | | |
| stream0 @--->@ in0 out @--->@ in |
| stream1 @--->@ in1 | +-----+------------+
| stream2 @--->@ in2 | |
+------------+ @ in3 | '--> Terminal
Here’s another example of a more complex graph which 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 |
If you encounter any issue or usability problem, please report it on the Babeltrace bug tracker (see <https://bugs.lttng.org/projects/babeltrace>).
The Babeltrace project shares some communication channels with the LTTng project (see <https://lttng.org/>).
The Babeltrace 2 project is the result of hard work by many regular developers and occasional contributors.
The current project maintainer is Jérémie Galarneau <mailto:firstname.lastname@example.org>.
This manual page is part of the Babeltrace 2 project.
Babeltrace is distributed under the MIT license (see <https://opensource.org/licenses/MIT>).
|14 September 2019||Babeltrace 2.0.4|