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.
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 traces's metadata.
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.
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.
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.
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.
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.
Connection
The link between an output port and an input port through
which messages flow when a trace processing graph runs.
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.
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.
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's output port sends
packet and event messages which belong to a single
stream, but it's not required.
Stream end
The end of a stream.
Discarded events
A count of discarded events within a given time interval
for a given stream.
Discarded packets
A count of discarded packets within a given time interval
for a given stream.
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's message iterators work one message at a time to
perform the trace conversion or analysis duty.
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.
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's object.
