4 :revdate: 5 October 2017
9 babeltrace-intro - Introduction to Babeltrace
14 This man page is an introduction to the Babeltrace project.
16 The <<what-is,WHAT IS BABELTRACE?>> section lists the parts of the
17 project and shows the major changes from Babeltrace{nbsp}1 to
18 Babeltrace{nbsp}2 while the <<concepts,BABELTRACE CONCEPTS>> section
19 defines the core concepts of Babeltrace.
21 The <<graph-repr,TRACE PROCESSING GRAPH REPRESENTATION>> section shows
22 how some <<concepts,concepts>> are visually represented in other
29 Babeltrace is an open-source software project of which the purpose is
31 https://en.wikipedia.org/wiki/Tracing_(software)[traces].
33 The Babeltrace project includes the following parts:
35 [[libbabeltrace]]Babeltrace library (libbabeltrace)::
36 A shared library with a C API.
38 With libbabeltrace, you can programmatically create <<plugin,plugins>>
39 and <<comp-cls,component classes>>, build and run <<graph,processing
40 graphs>>, and more (see the <<concepts,BABELTRACE CONCEPTS>> section for
41 more details about those concepts). All the other Babeltrace parts rely
44 [[babeltrace-1]]`babeltrace` command::
45 A command-line interface which uses libbabeltrace to load plugins,
46 create a trace processing graph, create components, and run the
49 You can also use `babeltrace` to list the available plugins or to query
50 an object from a component class.
52 See man:babeltrace(1).
54 [[python-bindings]]Babeltrace Python bindings::
55 A Python{nbsp}3 package which offers a Pythonic interface of
58 You can perform the same operations which are available in libbabeltrace
59 with the Python bindings, but in a really easier way and with less code.
61 Babeltrace project's plugins::
62 The Babeltrace <<plugin,plugins>> shipped with the project.
64 Those plugins are not special, in that they only rely on libbabeltrace
65 and you don't need them to use libbabeltrace, man:babeltrace(1), or the
68 The Babeltrace project's plugins are:
72 Common Trace Format input/output, including the LTTng live source.
74 See man:babeltrace-plugin-ctf(7).
77 Graph utilities specific to http://lttng.org/[LTTng] traces.
79 See man:babeltrace-plugin-lttng-utils(7).
84 See man:babeltrace-plugin-text(7).
87 Graph utilities (muxer, trimmer, counter, dummy sink).
89 See man:babeltrace-plugin-utils(7).
92 Python plugin provider::
93 A shared library which libbabeltrace tries to load to add support
94 for Babeltrace plugins written in Python.
96 The package you use to write a Python Babeltrace plugin is the one
97 provided by the Python bindings.
100 Changes since Babeltrace{nbsp}1
101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102 This man page is an introduction to Babeltrace{nbsp}2, a rewrite of
103 Babeltrace{nbsp}1 with a focus on extensibility and flexibility.
105 Babeltrace{nbsp}1 exists since 2010. The major improvements brought by
106 Babeltrace{nbsp}2 are:
108 * Full plugin support: any user can distribute a Babeltrace plugin and,
109 as long as <<libbabeltrace,libbabeltrace>> finds it, any application
110 linked to libbabeltrace can load it and use it.
112 Plugins are not just input and output formats: they provide source,
113 filter, and sink <<comp-cls,component classes>> so that you can connect
114 specialized, reusable components together in a graph to create a
115 customized trace conversion or analysis device.
117 * In order to support user components, all the objects of libbabeltrace
118 have a reference count. The possible reference cycles are handled
119 internally so that the library's API is clean and predictable. The two
120 reference counting functions, `bt_get()` and `bt_put()`, are all you
121 need to manage the lifetime of any Babeltrace object.
123 * All the parts of the Babeltrace project run on the major operating
124 systems, including Windows and macOS.
130 This section defines the main concepts of the Babeltrace project. These
131 concepts translate into types and functions in
132 <<libbabeltrace,libbabeltrace>> and its <<python-bindings,Python
133 bindings>>, but also as command-line actions and options in the
134 <<babeltrace-1,`babeltrace` command>>. The other Babeltrace man pages
135 assume that you are familiar with the following definitions.
137 Some Babeltrace concepts are interdependent: it is normal to jump from
138 one definition to another to understand the big picture.
140 [[comp-cls]]Component class::
141 A reusable class from which you can instantiate one or more
142 <<comp,component>> instances.
144 There are three types of component classes used to instantiate the three
145 types of components (source, filter, and sink).
147 A component class provides methods, one of which is an initialization
148 method, or constructor, to create a component. You pass _initialization
149 parameters_ to this method to customize the created component. For
150 example, the initialization method of the compcls:src.ctf.fs component
151 class accepts a mandatory manparam:source.ctf.fs:path parameter which is
152 the file system path to the trace(s). It also accepts an optional
153 manparam:source.ctf.fs:clock-class-offset-ns parameter which is an
154 offset, in nanoseconds, to add to all the clock classes found in the
158 A node within a <<graph,trace processing graph>>.
160 There are three types of components:
164 An input component which produces <<notif,notifications>>.
166 Examples: CTF files input, log file input, LTTng-live input, random
170 An intermediate component which can discard the notifications it
171 receives, transform them, augment them, sort them, or create new
174 Examples: filter which removes notifications based on an expression,
175 filter which adds debugging information to selected events, notification
176 multiplexer, trace trimmer.
179 An output component which consumes notifications and usually writes
180 them to one or more formatted files.
182 Examples: log file output, CTF files output, text output on the
186 Components are connected together within a <<graph,trace processing
187 graph>> through their <<port,ports>>. Source components have output
188 ports, sink components have input ports, and filter components have
191 A component is the instance of a <<comp-cls,component class>>. The terms
192 _component_ and _component instance_ are equivalent.
194 Within a trace processing graph, each component has a unique name. This
195 is not the name of its component class, but an instance name. If `human`
196 is a component class name, than `John` could be a component name.
199 A connection point, on a <<comp,component>>, from which are sent or
200 to which are received <<notif,notifications>> when the <<graph,trace
201 processing graph>> is running.
203 An output port is where notifications are sent. An input port is where
204 notifications are received. Source components have output ports, sink
205 components have input ports, and filter components have both.
207 An output port can only be connected to a single input port at a given
210 A filter or sink component receiving notifications from its input ports
211 is said to _consume_ notifications.
213 The link between an output port and input port is a <<conn,connection>>.
215 A component can dynamically add and remove ports while a graph is
216 running. For example, a compcls:filter.utils.muxer component always
217 makes sure that it has at least one available input port.
220 The link between an output <<port,port>> and an input port through
221 which <<notif,notifications>> flow when a <<graph,trace processing
224 [[notif]]Notification::
225 An atomic element sent from an output <<port,port>> to an
228 A source <<comp,component>> produces notifications, while a sink
229 component consumes them. A filter component can both consume and
230 produce notifications.
232 The main types of notifications are:
236 A trace event record within a packet.
239 The beginning of a packet within a stream.
241 A packet is a container of events.
244 The end of a packet within a stream.
247 The beginning of a stream.
249 A stream is a container of packets.
251 Usually, a given source component's output port sends packet and
252 event notifications which belong to a single stream.
258 A count of discarded events within a given time interval for a given
262 A count of discarded packets within a given time interval for a
266 [[graph]]Trace processing graph::
267 A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where
268 nodes are <<comp,components>> and <<notif,notifications>> flow from
269 output <<port,ports>> to input ports.
271 You can build a trace processing graph with
272 <<libbabeltrace,libbabeltrace>>, with the <<python-bindings,Babeltrace
273 Python bindings>>, or with the man:babeltrace-run(1) and
274 man:babeltrace-convert(1) commands.
276 When you _run_ a trace processing graph, the sink components consume
277 notifications from their input ports, making all the graph's components
278 work one notification at a time to perform the trace conversion or
282 A container of <<comp-cls,component classes>> as a shared library.
284 Each component class within a plugin has a type (source, filter, or
285 sink) and a name. The type and name pair is unique within a given
288 <<libbabeltrace,libbabeltrace>> can load a plugin (`.so` or `.dll` file)
289 at run time: the result is a plugin object in which you can find a
290 specific component class and instantiate it within a <<graph,trace
291 processing graph>> as a <<comp,component>>.
293 The <<babeltrace-1,`babeltrace` command>> uses the
294 'TYPE.PLUGIN.COMPCLS' format to identify a specific component
295 class within a specific plugin. 'TYPE' is either `source`, `filter`,
298 You can list the available Babeltrace plugins with the
299 man:babeltrace-list-plugins(1) command.
302 An operation with which you can get a named object from a
303 <<comp-cls,component class>>, possibly with the help of query
306 The plain text metadata stream of a CTF trace and the available LTTng
307 live sessions of a given LTTng relay daemon are examples of queries.
309 You can use the man:babeltrace-query(1) command to query a component
314 TRACE PROCESSING GRAPH REPRESENTATION
315 -------------------------------------
316 In the Babeltrace man pages, a component is represented with a box. The
317 box has the <<comp-cls,component class>> type, <<plugin,plugin>> name,
318 and component class name at the top. Just below, between square
319 brackets, is its component instance name within the <<graph,trace
320 processing graph>>. Each <<port,port>> is represented with an `@` symbol
321 on the edge of the component box with its name inside the box. Output
322 ports are on the right edge while input ports are on the left edge.
324 For example, here's a source component box:
337 This one is an instance of the compcls:src.ctf.fs component class named
338 `my-src`. It has three output ports named `stream0`, `stream1`, and
341 A trace processing graph is represented with multiple component boxes
342 connected together. The <<conn,connections>> are arrows from output
343 ports to input ports.
345 For example, here's a simple conversion graph:
348 +------------+ +-----------------+ +------------------+
349 | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
350 | [ctf] | | [muxer] | | [text] |
352 | stream0 @--->@ in0 out @--->@ in |
353 | stream1 @--->@ in1 | +------------------+
354 | stream2 @--->@ in2 |
355 +------------+ @ in3 |
359 Note that input port `in3` of component `muxer` is not currently
360 connected in this example.
362 Sometimes, we symbolically represent other resources which are consumed
363 from or produced by components. In this case, arrows are used, but they
364 do not go to or from port symbols (`@`). For example, in the graph above,
365 the `ctf` component consumes a CTF trace and the `text` component
366 prints to the console, so here's a more complete diagram:
372 | +------------+ +-----------------+ +------------------+
373 | | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
374 '->| [ctf] | | [muxer] | | [text] |
376 | stream0 @--->@ in0 out @--->@ in |
377 | stream1 @--->@ in1 | +--+---------------+
378 | stream2 @--->@ in2 | |
379 +------------+ @ in3 | '---> Console
383 Here's another example of a more complex graph which splits a specific
384 stream using some criteria:
387 +------------+ +-----------------+ +------------------+
388 | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
389 | [ctf-in] | | [muxer] | | [text] |
391 | stream0 @--->@ in0 out @--->@ in |
392 | stream1 @--->@ in1 | +------------------+
393 | stream2 @-. @ in2 |
394 +------------+ | +-----------------+ +-------------+
397 | +-------------------+ | |
398 | | flt.some.splitter | .->@ in |
399 | | [splitter] | | +-------------+
401 '->@ in A @-' +-------------+
402 | B @-. | sink.ctf.fs |
403 +-------------------+ | | [ctf-out1] |
410 include::common-footer.txt[]