NAME | DESCRIPTION | WHAT IS BABELTRACE? | BABELTRACE CONCEPTS | TRACE PROCESSING GRAPH REPRESENTATION | BUGS | RESOURCES | AUTHORS | COPYRIGHT | SEE ALSO | COLOPHON

BABELTRACE-INTRO(7)           Babeltrace manual          BABELTRACE-INTRO(7)

NAME         top

       babeltrace-intro - Introduction to Babeltrace

DESCRIPTION         top

       This man page is an introduction to the Babeltrace project.

       The WHAT IS BABELTRACE? section lists the parts of the project and
       shows the major changes from Babeltrace 1 to Babeltrace 2 while the
       BABELTRACE CONCEPTS section defines the core concepts of Babeltrace.

       The TRACE PROCESSING GRAPH REPRESENTATION section shows how some
       concepts are visually represented in other Babeltrace man pages.

WHAT IS BABELTRACE?         top

       Babeltrace 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 project includes the following parts:

       Babeltrace library (libbabeltrace)
           A shared library with a C API.

           With libbabeltrace, you can programmatically create plugins and
           component classes, build and run processing graphs, and more (see
           the BABELTRACE CONCEPTS section for more details about those
           concepts). All the other Babeltrace parts rely on this library.

       babeltrace command
           A command-line interface which uses libbabeltrace to load
           plugins, create a trace processing graph, create components, and
           run the graph.

           You can also use babeltrace to list the available plugins or to
           query an object from a component class.

           See babeltrace(1).

       Babeltrace Python bindings
           A Python 3 package which offers a Pythonic interface of
           libbabeltrace.

           You can perform the same operations which are available in
           libbabeltrace with the Python bindings, but in a really easier
           way and with less code.

       Babeltrace project’s plugins
           The Babeltrace plugins shipped with the project.

           Those plugins are not special, in that they only rely on
           libbabeltrace and you don’t need them to use libbabeltrace,
           babeltrace(1), or the Python bindings.

           The Babeltrace project’s plugins are:

           ctf
               Common Trace Format input/output, including the LTTng live
               source.

               See babeltrace-plugin-ctf(7).

           lttng-utils
               Graph utilities specific to LTTng (see <http://lttng.org/>)
               traces.

               See babeltrace-plugin-lttng-utils(7).

           text
               Text input/output.

               See babeltrace-plugin-text(7).

           utils
               Graph utilities (muxer, trimmer, counter, dummy sink).

               See babeltrace-plugin-utils(7).

       Python plugin provider
           A shared library which libbabeltrace tries to load to add support
           for Babeltrace plugins written in Python.

           The package you use to write a Python Babeltrace plugin is the
           one provided by the Python bindings.

   Changes since Babeltrace 1
       This man page is an introduction to Babeltrace 2, a rewrite of
       Babeltrace 1 with a focus on extensibility and flexibility.

       Babeltrace 1 exists since 2010. The major improvements brought by
       Babeltrace 2 are:

       ·   Full plugin support: any user can distribute a Babeltrace plugin
           and, as long as libbabeltrace finds it, any application linked to
           libbabeltrace can load it and use it.

           Plugins are not just input and output formats: they provide
           source, filter, and sink component classes so that you can
           connect specialized, reusable components together in a graph to
           create a customized trace conversion or analysis device.

       ·   In order to support user components, all the objects of
           libbabeltrace have a reference count. The possible reference
           cycles are handled internally so that the library’s API is clean
           and predictable. The two reference counting functions, bt_get()
           and bt_put(), are all you need to manage the lifetime of any
           Babeltrace object.

       ·   All the parts of the Babeltrace project run on the major
           operating systems, including Windows and macOS.

BABELTRACE CONCEPTS         top

       This section defines the main concepts of the Babeltrace project.
       These concepts translate into types and functions in libbabeltrace
       and its Python bindings, but also as command-line actions and options
       in the babeltrace command. The other Babeltrace man pages assume that
       you are familiar with the following definitions.

       Some Babeltrace concepts are interdependent: it is normal to jump
       from one definition to another to understand the big picture.

       Component class
           A reusable class from which you can instantiate one or more
           component instances.

           There are three types of component classes used to instantiate
           the three types of components (source, filter, and sink).

           A component class provides 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
           src.ctf.fs component class accepts a mandatory path parameter
           which is the file system path to the 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 found in the
           traces’s metadata.

       Component
           A node within a trace processing graph.

           There are three types of components:

           Source component
               An input component which produces notifications.

               Examples: CTF files input, log file input, LTTng-live input,
               random event generator.

           Filter component
               An intermediate component which can discard the notifications
               it receives, transform them, augment them, sort them, or
               create new ones.

               Examples: filter which removes notifications based on an
               expression, filter which adds debugging information to
               selected events, notification multiplexer, trace trimmer.

           Sink component
               An output component which consumes notifications and usually
               writes them to one or more formatted files.

               Examples: log file output, CTF files output, text output on
               the console.

           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 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 John
           could be a component name.

       Port
           A connection point, on a component, from which are sent or to
           which are received notifications when the trace processing graph
           is running.

           An output port is where notifications are sent. An input port is
           where notifications are received. Source components have output
           ports, sink components have input ports, and filter components
           have both.

           An output port can only be connected to a single input port at a
           given time.

           A filter or sink component receiving notifications from its input
           ports is said to consume notifications.

           The link between an output port and input port is a connection.

           A component can dynamically add and remove ports while a graph is
           running. For example, a filter.utils.muxer component always makes
           sure that it has at least one available input port.

       Connection
           The link between an output port and an input port through which
           notifications flow when a trace processing graph is running.

       Notification
           An atomic element sent from an output port to an input port.

           A source component produces notifications, while a sink component
           consumes them. A filter component can both consume and produce
           notifications.

           The main types of notifications are:

           Event
               A trace event record within a packet.

           Packet beginning
               The beginning of a packet within a stream.

               A packet is a container of events.

           Packet end
               The end of a packet within a stream.

           Stream beginning
               The beginning of a stream.

               A stream is a container of packets.

               Usually, a given source component’s output port sends packet
               and event notifications which belong to a single stream.

           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 notifications flow from output
           ports to input ports.

           You can build a trace processing graph with libbabeltrace, with
           the Babeltrace Python bindings, or with the babeltrace-run(1) and
           babeltrace-convert(1) commands.

           When you run a trace processing graph, the sink components
           consume notifications from their input ports, making all the
           graph’s components work one notification at a time to perform the
           trace conversion or analysis.

       Plugin
           A container of component classes as a shared library.

           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.

           libbabeltrace can load a plugin (.so or .dll 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 babeltrace command uses the TYPE.PLUGIN.COMPCLS format to
           identify a specific component class within a specific plugin.
           TYPE is either source, filter, or sink.

           You can list the available Babeltrace plugins with the
           babeltrace-list-plugins(1) command.

       Query
           An operation with which you can get a named object from a
           component class, possibly with the help of 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
           queries.

           You can use the babeltrace-query(1) command to query a component
           class’s object.

TRACE PROCESSING GRAPH REPRESENTATION         top

       In the Babeltrace man 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 instance name within the trace processing graph. Each port
       is represented with an @ symbol on the edge of the component box with
       its name inside the box. Output ports are on the right edge while
       input ports are on the left edge.

       For example, here’s a source component box:

           +------------+
           | src.ctf.fs |
           |  [my-src]  |
           |            |
           |    stream0 @
           |    stream1 @
           |    stream2 @
           +------------+

       This one is an instance of the src.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 currently
       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 (@). For example, in
       the graph above, the ctf component consumes a CTF trace and the text
       component prints to the console, so here’s a more complete diagram:

              CTF trace
                  |
           .------'
           |  +------------+    +-----------------+    +------------------+
           |  | src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
           '->|    [ctf]   |    |     [muxer]     |    |      [text]      |
              |            |    |                 |    |                  |
              |    stream0 @--->@ in0         out @--->@ in               |
              |    stream1 @--->@ in1             |    +--+---------------+
              |    stream2 @--->@ in2             |          |
              +------------+    @ in3             |          '---> Console
                                +-----------------+

       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          |
                                                      +-------------+

BUGS         top

       If you encounter any issue or usability problem, please report it on
       the Babeltrace bug tracker (see
       <https://bugs.linuxfoundation.org/buglist.cgi?product=Diamon&component=Babeltrace>).

RESOURCES         top

       The Babeltrace project shares some communication channels with the
       LTTng project (see <http://lttng.org/>).

       ·   Babeltrace website (see <http://diamon.org/babeltrace>)

       ·   Git repository (see
           <http://git.linuxfoundation.org/?p=diamon/babeltrace.git>)

       ·   EfficiOS GitHub organization (see <http://github.com/efficios/>)

       ·   Continuous integration (see
           <https://ci.lttng.org/job/babeltrace_master_build/>)

       ·   Mailing list (see <http://lists.lttng.org>) for support and
           development: lttng-dev@lists.lttng.org

       ·   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
           irc.oftc.net

AUTHORS         top

       The Babeltrace project is the result of efforts by many regular
       developers and occasional contributors.

       The current project maintainer is Jérémie Galarneau
       <mailto:jeremie.galarneau@efficios.com>.

COPYRIGHT         top

       This man page is part of the Babeltrace project.

       Babeltrace is distributed under the MIT license (see
       <https://opensource.org/licenses/MIT>).

SEE ALSO         top

       babeltrace(1)

COLOPHON         top

       This page is part of the babeltrace (trace read and write libraries
       and a trace converter) project.  Information about the project can be
       found at ⟨http://www.efficios.com/babeltrace⟩.  If you have a bug
       report for this manual page, send it to lttng-dev@lists.lttng.org.
       This page was obtained from the project's upstream Git repository
       ⟨git://git.efficios.com/babeltrace.git⟩ on 2017-11-25.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2017-11-23.)  If you discover any rendering problems in
       this HTML version of the page, or you believe there is a better or
       more up-to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not part
       of the original manual page), send a mail to man-pages@man7.org

Babeltrace 2.0.0-pre4          5 October 2017            BABELTRACE-INTRO(7)

Pages that refer to this page: babeltrace(1)babeltrace-convert(1)babeltrace-help(1)babeltrace-list-plugins(1)babeltrace-log(1)babeltrace-query(1)babeltrace-run(1)babeltrace-filter.lttng-utils.debug-info(7)babeltrace-filter.utils.muxer(7)babeltrace-filter.utils.trimmer(7)babeltrace-plugin-ctf(7)babeltrace-plugin-lttng-utils(7)babeltrace-plugin-text(7)babeltrace-plugin-utils(7)babeltrace-sink.ctf.fs(7)babeltrace-sink.text.pretty(7)babeltrace-sink.utils.counter(7)babeltrace-sink.utils.dummy(7)babeltrace-source.ctf.fs(7)babeltrace-source.ctf.lttng-live(7)babeltrace-source.text.dmesg(7)