doc/bindings/python/source/index.rst

   1 ..
   2    SPDX-FileCopyrightText: 2020 Philippe Proulx <eeppeliteloop@gmail.com>
   3    SPDX-License-Identifier: CC-BY-SA-4.0
   4
   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.