Commit | Line | Data |
---|---|---|
838dd456 PP |
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) |