Commit | Line | Data |
---|---|---|
2f37a969 PP |
1 | .. |
2 | SPDX-FileCopyrightText: 2020 Philippe Proulx <eeppeliteloop@gmail.com> | |
3 | SPDX-License-Identifier: CC-BY-SA-4.0 | |
4 | ||
ba64dfcc SM |
5 | .. include:: common.rst |
6 | ||
7 | Welcome! | |
8 | ======== | |
9 | Welcome to the `Babeltrace 2 <https://babeltrace.org/>`_ Python |~| 3 | |
10 | bindings documentation (version |version|). | |
11 | ||
12 | .. note:: | |
13 | ||
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. | |
17 | ||
18 | .. attention:: | |
19 | This documentation is **incomplete**. | |
20 | ||
21 | In the meantime: | |
22 | ||
23 | * See :ref:`examples` to learn how to accomplish common tasks. | |
24 | ||
25 | * Have a look at the | |
26 | :bt2link:`Babeltrace 2 C API documentation <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`. | |
27 | ||
28 | The Babeltrace |~| 2 Python bindings wrap all the functionalities | |
29 | of libbabeltrace2 in a reasonably systematic manner. | |
30 | ||
31 | **Contents**: | |
32 | ||
33 | .. toctree:: | |
34 | :maxdepth: 2 | |
35 | ||
36 | installation | |
37 | examples | |
38 | ||
39 | What's Babeltrace 2? | |
40 | -------------------- | |
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)>`_. | |
45 | ||
46 | The Babeltrace |~| 2 project contains: | |
47 | ||
48 | * A **library**, | |
49 | :bt2link:`libbabeltrace2 <https://babeltrace.org/docs/v@ver@/libbabeltrace2/>`, | |
50 | which all the other parts rely on. | |
51 | ||
52 | libbabeltrace2 offers a C99 interface. | |
53 | ||
54 | * A **command-line program**, :bt2man:`babeltrace2(1)`, which can | |
55 | convert and manipulate traces. | |
56 | ||
57 | * **Python 3 bindings** which offer a Pythonic interface of | |
58 | libbabeltrace2. | |
59 | ||
60 | This documentation is about those bindings. | |
61 | ||
62 | * "Standard" **plugins** which ship with the project. | |
63 | ||
64 | `Common Trace Format <https://diamon.org/ctf/>`_ (CTF) input and | |
65 | output, | |
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. | |
70 | ||
71 | With the Babeltrace |~| 2 Python bindings, you can write programs to | |
72 | do everything you can do, and more, with libbabeltrace2, that is: | |
73 | ||
74 | * Write custom source, filter, and sink *component classes* which | |
75 | you can package as Python *plugins*. | |
76 | ||
77 | Component classes are instantiated as components within a *trace | |
78 | processing graph* and are assembled to accomplish a trace manipulation | |
79 | or conversion job. | |
80 | ||
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. | |
85 | ||
86 | This is what the :command:`babeltrace2` CLI tool's ``convert`` and | |
87 | ``run`` commands do, for example. | |
88 | ||
89 | A trace processing graph contains connected components. The specific | |
90 | component topology determines the trace processing task to realize. | |
91 | ||
92 | .. figure:: images/basic-convert-graph.png | |
93 | ||
94 | A *conversion graph*, a specific trace processing graph. | |
95 | ||
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*. | |
100 | ||
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. | |
105 | ||
106 | Make sure to read the :bt2man:`babeltrace2-intro(7)` | |
107 | manual page to learn even more about the Babeltrace |~| 2 project and | |
108 | its core concepts. |