| 1 | .. include:: common.rst |
| 2 | |
| 3 | Welcome! |
| 4 | ======== |
| 5 | Welcome to the `Babeltrace 2 <https://babeltrace.org/>`_ Python |~| 3 |
| 6 | bindings documentation (version |version|). |
| 7 | |
| 8 | .. note:: |
| 9 | |
| 10 | This documentation (text and illustrations) is licensed under a |
| 11 | `Creative Commons Attribution-ShareAlike 4.0 International |
| 12 | <https://creativecommons.org/licenses/by-sa/4.0/legalcode>`_ license. |
| 13 | |
| 14 | .. attention:: |
| 15 | This documentation is **incomplete**. |
| 16 | |
| 17 | In the meantime: |
| 18 | |
| 19 | * See :ref:`examples` to learn how to accomplish common tasks. |
| 20 | |
| 21 | * Have a look at the |
| 22 | :bt2link:`Babeltrace 2 C API documentation <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`. |
| 23 | |
| 24 | The Babeltrace |~| 2 Python bindings wrap all the functionalities |
| 25 | of libbabeltrace2 in a reasonably systematic manner. |
| 26 | |
| 27 | **Contents**: |
| 28 | |
| 29 | .. toctree:: |
| 30 | :maxdepth: 2 |
| 31 | |
| 32 | installation |
| 33 | examples |
| 34 | |
| 35 | What's Babeltrace 2? |
| 36 | -------------------- |
| 37 | Babeltrace 2 is an open-source software project by |
| 38 | `EfficiOS <https://www.efficios.com/>`_; its purpose |
| 39 | is to process or convert |
| 40 | `traces <https://en.wikipedia.org/wiki/Tracing_(software)>`_. |
| 41 | |
| 42 | The Babeltrace |~| 2 project contains: |
| 43 | |
| 44 | * A **library**, |
| 45 | :bt2link:`libbabeltrace2 <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`, |
| 46 | which all the other parts rely on. |
| 47 | |
| 48 | libbabeltrace2 offers a C99 interface. |
| 49 | |
| 50 | * A **command-line program**, :bt2man:`babeltrace2(1)`, which can |
| 51 | convert and manipulate traces. |
| 52 | |
| 53 | * **Python 3 bindings** which offer a Pythonic interface of |
| 54 | libbabeltrace2. |
| 55 | |
| 56 | This documentation is about those bindings. |
| 57 | |
| 58 | * "Standard" **plugins** which ship with the project. |
| 59 | |
| 60 | `Common Trace Format <https://diamon.org/ctf/>`_ (CTF) input and |
| 61 | output, |
| 62 | :bt2link:`plain text <https://babeltrace.org/docs/v@ver@/man7/babeltrace2-plugin-text.7/>` |
| 63 | input and output, and various |
| 64 | :bt2link:`utilities <https://babeltrace.org/docs/v@ver@/man7/babeltrace2-plugin-utils.7/>` |
| 65 | are part of those plugins. |
| 66 | |
| 67 | With the Babeltrace |~| 2 Python bindings, you can write programs to |
| 68 | do everything you can do, and more, with libbabeltrace2, that is: |
| 69 | |
| 70 | * Write custom source, filter, and sink *component classes* which |
| 71 | you can package as Python *plugins*. |
| 72 | |
| 73 | Component classes are instantiated as components within a *trace |
| 74 | processing graph* and are assembled to accomplish a trace manipulation |
| 75 | or conversion job. |
| 76 | |
| 77 | * Load plugins (compiled shared object or Python modules), instantiate |
| 78 | their component classes within a trace processing graph, connect the |
| 79 | components as needed, and run the graph to accomplish a trace |
| 80 | manipulation or conversion job. |
| 81 | |
| 82 | This is what the :command:`babeltrace2` CLI tool's ``convert`` and |
| 83 | ``run`` commands do, for example. |
| 84 | |
| 85 | A trace processing graph contains connected components. The specific |
| 86 | component topology determines the trace processing task to realize. |
| 87 | |
| 88 | .. figure:: images/basic-convert-graph.png |
| 89 | |
| 90 | A *conversion graph*, a specific trace processing graph. |
| 91 | |
| 92 | Between the components of a trace processing graph, *messages* flow from |
| 93 | output ports to input ports following the configured connections through |
| 94 | *message iterators*. There are many types of messages, chief amongst |
| 95 | which is the *event message*. |
| 96 | |
| 97 | With the Babeltrace |~| 2 Python bindings, you can also query some |
| 98 | specific object from a component class (for example, the available LTTng |
| 99 | live sessions of an `LTTng <https://lttng.org/>`_ relay daemon). This is |
| 100 | what the :command:`babeltrace2` CLI tool's ``query`` command does, for example. |
| 101 | |
| 102 | Make sure to read the :bt2man:`babeltrace2-intro(7)` |
| 103 | manual page to learn even more about the Babeltrace |~| 2 project and |
| 104 | its core concepts. |