| 1 | babeltrace-intro(7) |
| 2 | =================== |
| 3 | :manpagetype: man page |
| 4 | :revdate: 5 October 2017 |
| 5 | |
| 6 | |
| 7 | NAME |
| 8 | ---- |
| 9 | babeltrace-intro - Introduction to Babeltrace |
| 10 | |
| 11 | |
| 12 | DESCRIPTION |
| 13 | ----------- |
| 14 | This man page is an introduction to the Babeltrace project. |
| 15 | |
| 16 | The <<what-is,WHAT IS BABELTRACE?>> section lists the parts of the |
| 17 | project and shows the major changes from Babeltrace{nbsp}1 to |
| 18 | Babeltrace{nbsp}2 while the <<concepts,BABELTRACE CONCEPTS>> section |
| 19 | defines the core concepts of Babeltrace. |
| 20 | |
| 21 | The <<graph-repr,TRACE PROCESSING GRAPH REPRESENTATION>> section shows |
| 22 | how some <<concepts,concepts>> are visually represented in other |
| 23 | Babeltrace man pages. |
| 24 | |
| 25 | |
| 26 | [[what-is]] |
| 27 | WHAT IS BABELTRACE? |
| 28 | ------------------- |
| 29 | Babeltrace is an open-source software project of which the purpose is |
| 30 | to process or convert |
| 31 | https://en.wikipedia.org/wiki/Tracing_(software)[traces]. |
| 32 | |
| 33 | The Babeltrace project includes the following parts: |
| 34 | |
| 35 | [[libbabeltrace]]Babeltrace library (libbabeltrace):: |
| 36 | A shared library with a C API. |
| 37 | + |
| 38 | With libbabeltrace, you can programmatically create <<plugin,plugins>> |
| 39 | and <<comp-cls,component classes>>, build and run <<graph,processing |
| 40 | graphs>>, and more (see the <<concepts,BABELTRACE CONCEPTS>> section for |
| 41 | more details about those concepts). All the other Babeltrace parts rely |
| 42 | on this library. |
| 43 | |
| 44 | [[babeltrace-1]]`babeltrace` command:: |
| 45 | A command-line interface which uses libbabeltrace to load plugins, |
| 46 | create a trace processing graph, create components, and run the |
| 47 | graph. |
| 48 | + |
| 49 | You can also use `babeltrace` to list the available plugins or to query |
| 50 | an object from a component class. |
| 51 | + |
| 52 | See man:babeltrace(1). |
| 53 | |
| 54 | [[python-bindings]]Babeltrace Python bindings:: |
| 55 | A Python{nbsp}3 package which offers a Pythonic interface of |
| 56 | libbabeltrace. |
| 57 | + |
| 58 | You can perform the same operations which are available in libbabeltrace |
| 59 | with the Python bindings, but in a really easier way and with less code. |
| 60 | |
| 61 | Babeltrace project's plugins:: |
| 62 | The Babeltrace <<plugin,plugins>> shipped with the project. |
| 63 | + |
| 64 | Those plugins are not special, in that they only rely on libbabeltrace |
| 65 | and you don't need them to use libbabeltrace, man:babeltrace(1), or the |
| 66 | Python bindings. |
| 67 | + |
| 68 | The Babeltrace project's plugins are: |
| 69 | + |
| 70 | -- |
| 71 | `ctf`:: |
| 72 | Common Trace Format input/output, including the LTTng live source. |
| 73 | + |
| 74 | See man:babeltrace-plugin-ctf(7). |
| 75 | |
| 76 | `lttng-utils`:: |
| 77 | Graph utilities specific to http://lttng.org/[LTTng] traces. |
| 78 | + |
| 79 | See man:babeltrace-plugin-lttng-utils(7). |
| 80 | |
| 81 | `text`:: |
| 82 | Text input/output. |
| 83 | + |
| 84 | See man:babeltrace-plugin-text(7). |
| 85 | |
| 86 | `utils`:: |
| 87 | Graph utilities (muxer, trimmer, counter, dummy sink). |
| 88 | + |
| 89 | See man:babeltrace-plugin-utils(7). |
| 90 | -- |
| 91 | |
| 92 | Python plugin provider:: |
| 93 | A shared library which libbabeltrace tries to load to add support |
| 94 | for Babeltrace plugins written in Python. |
| 95 | + |
| 96 | The package you use to write a Python Babeltrace plugin is the one |
| 97 | provided by the Python bindings. |
| 98 | |
| 99 | |
| 100 | Changes since Babeltrace{nbsp}1 |
| 101 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 102 | This man page is an introduction to Babeltrace{nbsp}2, a rewrite of |
| 103 | Babeltrace{nbsp}1 with a focus on extensibility and flexibility. |
| 104 | |
| 105 | Babeltrace{nbsp}1 exists since 2010. The major improvements brought by |
| 106 | Babeltrace{nbsp}2 are: |
| 107 | |
| 108 | * Full plugin support: any user can distribute a Babeltrace plugin and, |
| 109 | as long as <<libbabeltrace,libbabeltrace>> finds it, any application |
| 110 | linked to libbabeltrace can load it and use it. |
| 111 | + |
| 112 | Plugins are not just input and output formats: they provide source, |
| 113 | filter, and sink <<comp-cls,component classes>> so that you can connect |
| 114 | specialized, reusable components together in a graph to create a |
| 115 | customized trace conversion or analysis device. |
| 116 | |
| 117 | * In order to support user components, all the objects of libbabeltrace |
| 118 | have a reference count. The possible reference cycles are handled |
| 119 | internally so that the library's API is clean and predictable. The two |
| 120 | reference counting functions, `bt_get()` and `bt_put()`, are all you |
| 121 | need to manage the lifetime of any Babeltrace object. |
| 122 | |
| 123 | * All the parts of the Babeltrace project run on the major operating |
| 124 | systems, including Windows and macOS. |
| 125 | |
| 126 | |
| 127 | [[concepts]] |
| 128 | BABELTRACE CONCEPTS |
| 129 | ------------------- |
| 130 | This section defines the main concepts of the Babeltrace project. These |
| 131 | concepts translate into types and functions in |
| 132 | <<libbabeltrace,libbabeltrace>> and its <<python-bindings,Python |
| 133 | bindings>>, but also as command-line actions and options in the |
| 134 | <<babeltrace-1,`babeltrace` command>>. The other Babeltrace man pages |
| 135 | assume that you are familiar with the following definitions. |
| 136 | |
| 137 | Some Babeltrace concepts are interdependent: it is normal to jump from |
| 138 | one definition to another to understand the big picture. |
| 139 | |
| 140 | [[comp-cls]]Component class:: |
| 141 | A reusable class from which you can instantiate one or more |
| 142 | <<comp,component>> instances. |
| 143 | + |
| 144 | There are three types of component classes used to instantiate the three |
| 145 | types of components (source, filter, and sink). |
| 146 | + |
| 147 | A component class provides methods, one of which is an initialization |
| 148 | method, or constructor, to create a component. You pass _initialization |
| 149 | parameters_ to this method to customize the created component. For |
| 150 | example, the initialization method of the compcls:src.ctf.fs component |
| 151 | class accepts a mandatory manparam:source.ctf.fs:path parameter which is |
| 152 | the file system path to the trace(s). It also accepts an optional |
| 153 | manparam:source.ctf.fs:clock-class-offset-ns parameter which is an |
| 154 | offset, in nanoseconds, to add to all the clock classes found in the |
| 155 | traces's metadata. |
| 156 | |
| 157 | [[comp]]Component:: |
| 158 | A node within a <<graph,trace processing graph>>. |
| 159 | + |
| 160 | There are three types of components: |
| 161 | + |
| 162 | -- |
| 163 | Source component:: |
| 164 | An input component which produces <<notif,notifications>>. |
| 165 | + |
| 166 | Examples: CTF files input, log file input, LTTng-live input, random |
| 167 | event generator. |
| 168 | |
| 169 | Filter component:: |
| 170 | An intermediate component which can discard the notifications it |
| 171 | receives, transform them, augment them, sort them, or create new |
| 172 | ones. |
| 173 | + |
| 174 | Examples: filter which removes notifications based on an expression, |
| 175 | filter which adds debugging information to selected events, notification |
| 176 | multiplexer, trace trimmer. |
| 177 | |
| 178 | Sink component:: |
| 179 | An output component which consumes notifications and usually writes |
| 180 | them to one or more formatted files. |
| 181 | + |
| 182 | Examples: log file output, CTF files output, text output on the |
| 183 | console. |
| 184 | -- |
| 185 | + |
| 186 | Components are connected together within a <<graph,trace processing |
| 187 | graph>> through their <<port,ports>>. Source components have output |
| 188 | ports, sink components have input ports, and filter components have |
| 189 | both. |
| 190 | + |
| 191 | A component is the instance of a <<comp-cls,component class>>. The terms |
| 192 | _component_ and _component instance_ are equivalent. |
| 193 | + |
| 194 | Within a trace processing graph, each component has a unique name. This |
| 195 | is not the name of its component class, but an instance name. If `human` |
| 196 | is a component class name, than `John` could be a component name. |
| 197 | |
| 198 | [[port]]Port:: |
| 199 | A connection point, on a <<comp,component>>, from which are sent or |
| 200 | to which are received <<notif,notifications>> when the <<graph,trace |
| 201 | processing graph>> is running. |
| 202 | + |
| 203 | An output port is where notifications are sent. An input port is where |
| 204 | notifications are received. Source components have output ports, sink |
| 205 | components have input ports, and filter components have both. |
| 206 | + |
| 207 | An output port can only be connected to a single input port at a given |
| 208 | time. |
| 209 | + |
| 210 | A filter or sink component receiving notifications from its input ports |
| 211 | is said to _consume_ notifications. |
| 212 | + |
| 213 | The link between an output port and input port is a <<conn,connection>>. |
| 214 | + |
| 215 | A component can dynamically add and remove ports while a graph is |
| 216 | running. For example, a compcls:filter.utils.muxer component always |
| 217 | makes sure that it has at least one available input port. |
| 218 | |
| 219 | [[conn]]Connection:: |
| 220 | The link between an output <<port,port>> and an input port through |
| 221 | which <<notif,notifications>> flow when a <<graph,trace processing |
| 222 | graph>> is running. |
| 223 | |
| 224 | [[notif]]Notification:: |
| 225 | An atomic element sent from an output <<port,port>> to an |
| 226 | input port. |
| 227 | + |
| 228 | A source <<comp,component>> produces notifications, while a sink |
| 229 | component consumes them. A filter component can both consume and |
| 230 | produce notifications. |
| 231 | + |
| 232 | The main types of notifications are: |
| 233 | + |
| 234 | -- |
| 235 | Event:: |
| 236 | A trace event record within a packet. |
| 237 | |
| 238 | Packet beginning:: |
| 239 | The beginning of a packet within a stream. |
| 240 | + |
| 241 | A packet is a container of events. |
| 242 | |
| 243 | Packet end:: |
| 244 | The end of a packet within a stream. |
| 245 | |
| 246 | Stream beginning:: |
| 247 | The beginning of a stream. |
| 248 | + |
| 249 | A stream is a container of packets. |
| 250 | + |
| 251 | Usually, a given source component's output port sends packet and |
| 252 | event notifications which belong to a single stream. |
| 253 | |
| 254 | Stream end:: |
| 255 | The end of a stream. |
| 256 | |
| 257 | Discarded events:: |
| 258 | A count of discarded events within a given time interval for a given |
| 259 | stream. |
| 260 | |
| 261 | Discarded packets:: |
| 262 | A count of discarded packets within a given time interval for a |
| 263 | given stream. |
| 264 | -- |
| 265 | |
| 266 | [[graph]]Trace processing graph:: |
| 267 | A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where |
| 268 | nodes are <<comp,components>> and <<notif,notifications>> flow from |
| 269 | output <<port,ports>> to input ports. |
| 270 | + |
| 271 | You can build a trace processing graph with |
| 272 | <<libbabeltrace,libbabeltrace>>, with the <<python-bindings,Babeltrace |
| 273 | Python bindings>>, or with the man:babeltrace-run(1) and |
| 274 | man:babeltrace-convert(1) commands. |
| 275 | + |
| 276 | When you _run_ a trace processing graph, the sink components consume |
| 277 | notifications from their input ports, making all the graph's components |
| 278 | work one notification at a time to perform the trace conversion or |
| 279 | analysis. |
| 280 | |
| 281 | [[plugin]]Plugin:: |
| 282 | A container of <<comp-cls,component classes>> as a shared library. |
| 283 | + |
| 284 | Each component class within a plugin has a type (source, filter, or |
| 285 | sink) and a name. The type and name pair is unique within a given |
| 286 | plugin. |
| 287 | + |
| 288 | <<libbabeltrace,libbabeltrace>> can load a plugin (`.so` or `.dll` file) |
| 289 | at run time: the result is a plugin object in which you can find a |
| 290 | specific component class and instantiate it within a <<graph,trace |
| 291 | processing graph>> as a <<comp,component>>. |
| 292 | + |
| 293 | The <<babeltrace-1,`babeltrace` command>> uses the |
| 294 | 'TYPE.PLUGIN.COMPCLS' format to identify a specific component |
| 295 | class within a specific plugin. 'TYPE' is either `source`, `filter`, |
| 296 | or `sink`. |
| 297 | + |
| 298 | You can list the available Babeltrace plugins with the |
| 299 | man:babeltrace-list-plugins(1) command. |
| 300 | |
| 301 | [[query]]Query:: |
| 302 | An operation with which you can get a named object from a |
| 303 | <<comp-cls,component class>>, possibly with the help of query |
| 304 | parameters. |
| 305 | + |
| 306 | The plain text metadata stream of a CTF trace and the available LTTng |
| 307 | live sessions of a given LTTng relay daemon are examples of queries. |
| 308 | + |
| 309 | You can use the man:babeltrace-query(1) command to query a component |
| 310 | class's object. |
| 311 | |
| 312 | |
| 313 | [[graph-repr]] |
| 314 | TRACE PROCESSING GRAPH REPRESENTATION |
| 315 | ------------------------------------- |
| 316 | In the Babeltrace man pages, a component is represented with a box. The |
| 317 | box has the <<comp-cls,component class>> type, <<plugin,plugin>> name, |
| 318 | and component class name at the top. Just below, between square |
| 319 | brackets, is its component instance name within the <<graph,trace |
| 320 | processing graph>>. Each <<port,port>> is represented with an `@` symbol |
| 321 | on the edge of the component box with its name inside the box. Output |
| 322 | ports are on the right edge while input ports are on the left edge. |
| 323 | |
| 324 | For example, here's a source component box: |
| 325 | |
| 326 | ---- |
| 327 | +------------+ |
| 328 | | src.ctf.fs | |
| 329 | | [my-src] | |
| 330 | | | |
| 331 | | stream0 @ |
| 332 | | stream1 @ |
| 333 | | stream2 @ |
| 334 | +------------+ |
| 335 | ---- |
| 336 | |
| 337 | This one is an instance of the compcls:src.ctf.fs component class named |
| 338 | `my-src`. It has three output ports named `stream0`, `stream1`, and |
| 339 | `stream2`. |
| 340 | |
| 341 | A trace processing graph is represented with multiple component boxes |
| 342 | connected together. The <<conn,connections>> are arrows from output |
| 343 | ports to input ports. |
| 344 | |
| 345 | For example, here's a simple conversion graph: |
| 346 | |
| 347 | ---- |
| 348 | +------------+ +-----------------+ +------------------+ |
| 349 | | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty | |
| 350 | | [ctf] | | [muxer] | | [text] | |
| 351 | | | | | | | |
| 352 | | stream0 @--->@ in0 out @--->@ in | |
| 353 | | stream1 @--->@ in1 | +------------------+ |
| 354 | | stream2 @--->@ in2 | |
| 355 | +------------+ @ in3 | |
| 356 | +-----------------+ |
| 357 | ---- |
| 358 | |
| 359 | Note that input port `in3` of component `muxer` is not currently |
| 360 | connected in this example. |
| 361 | |
| 362 | Sometimes, we symbolically represent other resources which are consumed |
| 363 | from or produced by components. In this case, arrows are used, but they |
| 364 | do not go to or from port symbols (`@`). For example, in the graph above, |
| 365 | the `ctf` component consumes a CTF trace and the `text` component |
| 366 | prints to the console, so here's a more complete diagram: |
| 367 | |
| 368 | ---- |
| 369 | CTF trace |
| 370 | | |
| 371 | .------' |
| 372 | | +------------+ +-----------------+ +------------------+ |
| 373 | | | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty | |
| 374 | '->| [ctf] | | [muxer] | | [text] | |
| 375 | | | | | | | |
| 376 | | stream0 @--->@ in0 out @--->@ in | |
| 377 | | stream1 @--->@ in1 | +--+---------------+ |
| 378 | | stream2 @--->@ in2 | | |
| 379 | +------------+ @ in3 | '---> Console |
| 380 | +-----------------+ |
| 381 | ---- |
| 382 | |
| 383 | Here's another example of a more complex graph which splits a specific |
| 384 | stream using some criteria: |
| 385 | |
| 386 | ---- |
| 387 | +------------+ +-----------------+ +------------------+ |
| 388 | | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty | |
| 389 | | [ctf-in] | | [muxer] | | [text] | |
| 390 | | | | | | | |
| 391 | | stream0 @--->@ in0 out @--->@ in | |
| 392 | | stream1 @--->@ in1 | +------------------+ |
| 393 | | stream2 @-. @ in2 | |
| 394 | +------------+ | +-----------------+ +-------------+ |
| 395 | | | sink.ctf.fs | |
| 396 | | | [ctf-out0] | |
| 397 | | +-------------------+ | | |
| 398 | | | flt.some.splitter | .->@ in | |
| 399 | | | [splitter] | | +-------------+ |
| 400 | | | | | |
| 401 | '->@ in A @-' +-------------+ |
| 402 | | B @-. | sink.ctf.fs | |
| 403 | +-------------------+ | | [ctf-out1] | |
| 404 | | | | |
| 405 | '->@ in | |
| 406 | +-------------+ |
| 407 | ---- |
| 408 | |
| 409 | |
| 410 | include::common-footer.txt[] |
| 411 | |
| 412 | |
| 413 | SEE ALSO |
| 414 | -------- |
| 415 | man:babeltrace(1) |