projects / babeltrace.git / blame
| Commit | Line | Data |
|---|---|---|
| ba64dfcc SM |
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. |