2 SPDX-FileCopyrightText: 2020 Philippe Proulx <eeppeliteloop@gmail.com>
3 SPDX-License-Identifier: CC-BY-SA-4.0
5 .. include:: common.rst
9 Welcome to the `Babeltrace 2 <https://babeltrace.org/>`_ Python |~| 3
10 bindings documentation (version |version|).
14 This documentation (text and illustrations) is licensed under a
15 `Creative Commons Attribution-ShareAlike 4.0 International
16 <https://creativecommons.org/licenses/by-sa/4.0/legalcode>`_ license.
19 This documentation is **incomplete**.
23 * See :ref:`examples` to learn how to accomplish common tasks.
26 :bt2link:`Babeltrace 2 C API documentation <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`.
28 The Babeltrace |~| 2 Python bindings wrap all the functionalities
29 of libbabeltrace2 in a reasonably systematic manner.
41 Babeltrace 2 is an open-source software project by
42 `EfficiOS <https://www.efficios.com/>`_; its purpose
43 is to process or convert
44 `traces <https://en.wikipedia.org/wiki/Tracing_(software)>`_.
46 The Babeltrace |~| 2 project contains:
49 :bt2link:`libbabeltrace2 <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`,
50 which all the other parts rely on.
52 libbabeltrace2 offers a C99 interface.
54 * A **command-line program**, :bt2man:`babeltrace2(1)`, which can
55 convert and manipulate traces.
57 * **Python 3 bindings** which offer a Pythonic interface of
60 This documentation is about those bindings.
62 * "Standard" **plugins** which ship with the project.
64 `Common Trace Format <https://diamon.org/ctf/>`_ (CTF) input and
66 :bt2link:`plain text <https://babeltrace.org/docs/v@ver@/man7/babeltrace2-plugin-text.7/>`
67 input and output, and various
68 :bt2link:`utilities <https://babeltrace.org/docs/v@ver@/man7/babeltrace2-plugin-utils.7/>`
69 are part of those plugins.
71 With the Babeltrace |~| 2 Python bindings, you can write programs to
72 do everything you can do, and more, with libbabeltrace2, that is:
74 * Write custom source, filter, and sink *component classes* which
75 you can package as Python *plugins*.
77 Component classes are instantiated as components within a *trace
78 processing graph* and are assembled to accomplish a trace manipulation
81 * Load plugins (compiled shared object or Python modules), instantiate
82 their component classes within a trace processing graph, connect the
83 components as needed, and run the graph to accomplish a trace
84 manipulation or conversion job.
86 This is what the :command:`babeltrace2` CLI tool's ``convert`` and
87 ``run`` commands do, for example.
89 A trace processing graph contains connected components. The specific
90 component topology determines the trace processing task to realize.
92 .. figure:: images/basic-convert-graph.png
94 A *conversion graph*, a specific trace processing graph.
96 Between the components of a trace processing graph, *messages* flow from
97 output ports to input ports following the configured connections through
98 *message iterators*. There are many types of messages, chief amongst
99 which is the *event message*.
101 With the Babeltrace |~| 2 Python bindings, you can also query some
102 specific object from a component class (for example, the available LTTng
103 live sessions of an `LTTng <https://lttng.org/>`_ relay daemon). This is
104 what the :command:`babeltrace2` CLI tool's ``query`` command does, for example.
106 Make sure to read the :bt2man:`babeltrace2-intro(7)`
107 manual page to learn even more about the Babeltrace |~| 2 project and