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 | .. _examples: | |
8 | ||
9 | Examples | |
10 | ======== | |
11 | This section contains a few short and straightforward examples which | |
12 | show how to use the Babeltrace |~| 2 Python bindings. | |
13 | ||
14 | The :mod:`bt2` package provides the Babeltrace |~| 2 Python bindings. | |
15 | Note that the :mod:`babeltrace` package is part of the Babeltrace |~| 1 | |
16 | project: it's somewhat out-of-date and not compatible with the | |
17 | :mod:`bt2` package. | |
18 | ||
19 | Assume that all the examples below are named :file:`example.py`. | |
20 | ||
21 | .. _examples_tcmi: | |
22 | ||
23 | Iterate trace events | |
24 | -------------------- | |
25 | The most convenient and high-level way to iterate the events of one or | |
26 | more traces is with a :class:`bt2.TraceCollectionMessageIterator` | |
27 | object. | |
28 | ||
29 | A :class:`bt2.TraceCollectionMessageIterator` object roughly offers the | |
30 | same features as the ``convert`` command of the :command:`babeltrace2` | |
31 | command-line program (see the :bt2man:`babeltrace2-convert(1)` manual | |
32 | page), but in a programmatic, Pythonic way. | |
33 | ||
34 | As of Babeltrace |~| |version|, the trace collection message iterator | |
35 | class is a Python bindings-only feature: the Python code uses | |
36 | libbabeltrace2 internally, but the latter does not offer this utility as | |
37 | such. | |
38 | ||
39 | The :class:`bt2.TraceCollectionMessageIterator` interface features: | |
40 | ||
41 | * **Automatic source component (trace format) discovery**. | |
42 | ||
43 | ``convert`` command equivalent example: | |
44 | ||
45 | .. code-block:: text | |
46 | ||
47 | $ babeltrace2 /path/to/my/trace | |
48 | ||
49 | * **Explicit component class instantiation**. | |
50 | ||
51 | ``convert`` command equivalent example: | |
52 | ||
53 | .. code-block:: text | |
54 | ||
55 | $ babeltrace2 --component=source.my.format | |
56 | ||
57 | * **Passing initialization parameters to both auto-discovered and | |
58 | explicitly created components**. | |
59 | ||
60 | ``convert`` command equivalent example: | |
61 | ||
62 | .. code-block:: text | |
63 | ||
64 | $ babeltrace2 /path/to/my/trace --params=detailed=no \ | |
65 | --component=source.ctf.fs \ | |
66 | --params='inputs=["/path/to/my/trace"]' | |
67 | ||
68 | * **Trace event muxing**. | |
69 | ||
70 | The message iterator muxes (combines) the events from multiple | |
71 | compatible streams into a single, time-sorted sequence of events. | |
72 | ||
73 | .. code-block:: text | |
74 | ||
75 | $ babeltrace2 /path/to/trace1 /path/to/trace2 /path/to/trace3 | |
76 | ||
77 | * **Stream intersection mode**. | |
78 | ||
79 | ``convert`` command equivalent example: | |
80 | ||
81 | .. code-block:: text | |
82 | ||
83 | $ babeltrace2 /path/to/my/trace --stream-intersection | |
84 | ||
85 | * **Stream trimming with beginning and/or end times**. | |
86 | ||
87 | ``convert`` command equivalent example: | |
88 | ||
89 | .. code-block:: text | |
90 | ||
91 | $ babeltrace2 /path/to/my/trace --begin=22:14:38 --end=22:15:07 | |
92 | ||
93 | While the :command:`babeltrace2 convert` command creates a ``sink.text.pretty`` | |
94 | component class (by default) to pretty-print events as plain text lines, | |
95 | a :class:`bt2.TraceCollectionMessageIterator` object is a Python | |
96 | iterator which makes its user a message consumer (there's no sink | |
97 | component):: | |
98 | ||
99 | import bt2 | |
100 | ||
101 | for msg in bt2.TraceCollectionMessageIterator('/path/to/trace'): | |
102 | if type(msg) is bt2._EventMessageConst: | |
103 | print(msg.event.name) | |
104 | ||
105 | .. _examples_tcmi_autodisc: | |
106 | ||
107 | Discover traces | |
108 | ~~~~~~~~~~~~~~~ | |
109 | Pass one or more file paths, directory paths, or other strings when you | |
110 | build a :class:`bt2.TraceCollectionMessageIterator` object to let it | |
111 | automatically determine which source components to create for you. | |
112 | ||
113 | If you pass a directory path, the message iterator traverses the | |
114 | directory recursively to find traces, automatically selecting the | |
115 | appropriate source component classes to instantiate. | |
116 | ||
117 | The :class:`bt2.TraceCollectionMessageIterator` object and the | |
118 | :command:`babeltrace2 convert` CLI command share the same automatic | |
119 | component discovery algorithm. See the | |
120 | :bt2link:`Create implicit components from non-option arguments <https://babeltrace.org/docs/v@ver@/man1/babeltrace2-convert.1/#doc-comp-create-impl-non-opt>` | |
121 | section of the :bt2man:`babeltrace2-convert(1)` manual page for more | |
122 | details. | |
123 | ||
124 | The following example shows how to use a | |
125 | :class:`bt2.TraceCollectionMessageIterator` object to automatically | |
126 | discover one or more traces from a single path (file or directory). For | |
127 | each trace event, the example prints its name:: | |
128 | ||
129 | import bt2 | |
130 | import sys | |
131 | ||
132 | # Get the trace path from the first command-line argument. | |
133 | path = sys.argv[1] | |
134 | ||
135 | # Create a trace collection message iterator with this path. | |
136 | msg_it = bt2.TraceCollectionMessageIterator(path) | |
137 | ||
138 | # Iterate the trace messages. | |
139 | for msg in msg_it: | |
140 | # `bt2._EventMessageConst` is the Python type of an event message. | |
141 | if type(msg) is bt2._EventMessageConst: | |
142 | # An event message holds a trace event. | |
143 | event = msg.event | |
144 | ||
145 | # Print event's name. | |
146 | print(event.name) | |
147 | ||
148 | Run this example: | |
149 | ||
150 | .. code-block:: text | |
151 | ||
152 | $ python3 example.py /path/to/one/or/more/traces | |
153 | ||
154 | Output example: | |
155 | ||
156 | .. code-block:: text | |
157 | ||
158 | kmem_kmalloc | |
159 | kmem_kfree | |
160 | kmem_cache_alloc_node | |
161 | block_getrq | |
162 | kmem_kmalloc | |
163 | block_plug | |
164 | kmem_kfree | |
165 | block_rq_insert | |
166 | kmem_kmalloc | |
167 | kmem_kfree | |
168 | kmem_kmalloc | |
169 | kmem_kfree | |
170 | ||
171 | The example above is simplistic; it does not catch the exceptions that | |
172 | some statements can raise: | |
173 | ||
174 | * ``bt2.TraceCollectionMessageIterator(path)`` raises an exception if | |
175 | it cannot find any trace. | |
176 | ||
177 | * Each iteration of the loop, or, more precisely, the | |
178 | :meth:`bt2.TraceCollectionMessageIterator.__next__` method, raises | |
179 | an exception if there's any error during the iteration process. | |
180 | ||
181 | For example, an internal source component message iterator can fail | |
182 | when trying to decode a malformed trace file. | |
183 | ||
184 | .. _examples_tcmi_expl: | |
185 | ||
186 | Create explicit source components | |
187 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
188 | If `automatic source component discovery <#examples-tcmi-autodisc>`_ | |
189 | doesn't work for you (for example, because the source component class | |
190 | you actually need to instantiate doesn't offer the | |
191 | ``babeltrace.support-info`` query object), create explicit source | |
192 | components when you build a :class:`bt2.TraceCollectionMessageIterator` | |
193 | object. | |
194 | ||
195 | The following example builds a trace collection message iterator to | |
196 | explicitly instantiate a ``source.ctf.fs`` component class (found in the | |
197 | ``ctf`` plugin). Again, for each trace event, the example prints its | |
198 | name:: | |
199 | ||
200 | import bt2 | |
201 | import sys | |
202 | ||
203 | # Find the `ctf` plugin (shipped with Babeltrace 2). | |
204 | ctf_plugin = bt2.find_plugin('ctf') | |
205 | ||
206 | # Get the `source.ctf.fs` component class from the plugin. | |
207 | fs_cc = ctf_plugin.source_component_classes['fs'] | |
208 | ||
209 | # Create a trace collection message iterator, instantiating a single | |
210 | # `source.ctf.fs` component class with the `inputs` initialization | |
211 | # parameter set to open a single CTF trace. | |
212 | msg_it = bt2.TraceCollectionMessageIterator(bt2.ComponentSpec(fs_cc, { | |
213 | # Get the CTF trace path from the first command-line argument. | |
214 | 'inputs': [sys.argv[1]], | |
215 | })) | |
216 | ||
217 | # Iterate the trace messages. | |
218 | for msg in msg_it: | |
219 | # `bt2._EventMessageConst` is the Python type of an event message. | |
220 | if type(msg) is bt2._EventMessageConst: | |
221 | # Print event's name. | |
222 | print(msg.event.name) | |
223 | ||
224 | Run this example: | |
225 | ||
226 | .. code-block:: text | |
227 | ||
228 | $ python3 example.py /path/to/ctf/trace | |
229 | ||
230 | Output example: | |
231 | ||
232 | .. code-block:: text | |
233 | ||
234 | kmem_kmalloc | |
235 | kmem_kfree | |
236 | kmem_cache_alloc_node | |
237 | block_getrq | |
238 | kmem_kmalloc | |
239 | block_plug | |
240 | kmem_kfree | |
241 | block_rq_insert | |
242 | kmem_kmalloc | |
243 | kmem_kfree | |
244 | kmem_kmalloc | |
245 | kmem_kfree | |
246 | ||
247 | The example above looks similar to the previous one using | |
248 | `automatic source component discovery <#examples-tcmi-autodisc>`_, | |
249 | but there are notable differences: | |
250 | ||
251 | * A ``source.ctf.fs`` component expects to receive the path to a | |
252 | *single* `CTF <https://diamon.org/ctf/>`_ trace (a directory | |
253 | containing a file named ``metadata``). | |
254 | ||
255 | Unlike the previous example, you must pass the exact | |
256 | :abbr:`CTF (Common Trace Format)` trace directory path, *not* a | |
257 | parent directory path. | |
258 | ||
259 | * Unlike the previous example, the example above can only read a single | |
260 | trace. | |
261 | ||
262 | If you want to read multiple :abbr:`CTF (Common Trace Format)` traces | |
263 | using explicit component class instantiation with a single trace | |
264 | collection message iterator, you must create one ``source.ctf.fs`` | |
265 | component per trace. | |
266 | ||
267 | Note that the :class:`bt2.ComponentSpec` class offers the | |
268 | :meth:`from_named_plugin_and_component_class` convenience static method | |
269 | which finds the plugin and component class for you. You could therefore | |
270 | rewrite the trace collection message iterator creation part of the | |
271 | example above as:: | |
272 | ||
273 | # Create a trace collection message iterator, instantiating a single | |
274 | # `source.ctf.fs` component class with the `inputs` initialization | |
275 | # parameter set to open a single CTF trace. | |
276 | msg_it = bt2.TraceCollectionMessageIterator( | |
277 | bt2.ComponentSpec.from_named_plugin_and_component_class('ctf', 'fs', { | |
278 | # Get the CTF trace path from the first command-line argument. | |
279 | 'inputs': [sys.argv[1]], | |
280 | }) | |
281 | ) | |
282 | ||
283 | .. _examples_tcmi_ev_field: | |
284 | ||
285 | Get a specific event field's value | |
286 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
287 | The :ref:`examples_tcmi_autodisc` and :ref:`examples_tcmi_expl` examples | |
288 | show that a :class:`bt2.TraceCollectionMessageIterator` iterates the | |
289 | time-sorted *messages* of one or more traces. | |
290 | ||
291 | One specific type of message is :class:`bt2._EventMessageConst`, which | |
292 | holds a trace event object. | |
293 | ||
294 | .. note:: | |
295 | ||
296 | Everything you can find in the :mod:`bt2` package is publicly | |
297 | accessible. | |
298 | ||
299 | Names which start with ``_`` (underscore), like | |
300 | :class:`bt2._EventMessageConst`, indicate that you can't | |
301 | *instantiate* such a class (you cannot call the class). However, the | |
302 | type itself remains public so that you can use its name to check an | |
303 | object's type: | |
304 | ||
305 | .. code-block:: python | |
306 | ||
307 | if type(msg) is bt2._EventMessageConst: | |
308 | # ... | |
309 | ||
310 | .. code-block:: python | |
311 | ||
312 | if isinstance(field, bt2._IntegerFieldConst): | |
313 | # ... | |
314 | ||
315 | Access an event object's field by using the event as a simple mapping | |
316 | (like a read-only :class:`dict`), where keys are field names. The field | |
317 | can belong to any part of the event (contexts or payload) and to its | |
318 | packet's context, if any:: | |
319 | ||
320 | import bt2 | |
321 | import sys | |
322 | ||
323 | # Create a trace collection message iterator from the first | |
324 | # command-line argument. | |
325 | msg_it = bt2.TraceCollectionMessageIterator(sys.argv[1]) | |
326 | ||
327 | # Iterate the trace messages. | |
328 | for msg in msg_it: | |
329 | # `bt2._EventMessageConst` is the Python type of an event message. | |
330 | # Only keep such messages. | |
331 | if type(msg) is not bt2._EventMessageConst: | |
332 | continue | |
333 | ||
334 | # An event message holds a trace event. | |
335 | event = msg.event | |
336 | ||
337 | # Only check `sched_switch` events. | |
338 | if event.name != 'sched_switch': | |
339 | continue | |
340 | ||
341 | # In an LTTng trace, the `cpu_id` field is a packet context field. | |
342 | # The mapping interface of `event` can still find it. | |
343 | cpu_id = event['cpu_id'] | |
344 | ||
345 | # Previous and next process short names are found in the event's | |
346 | # `prev_comm` and `next_comm` fields. | |
347 | prev_comm = event['prev_comm'] | |
348 | next_comm = event['next_comm'] | |
349 | ||
350 | # Print line, using field values. | |
351 | msg = 'CPU {}: Switching process `{}` → `{}`' | |
352 | print(msg.format(cpu_id, prev_comm, next_comm)) | |
353 | ||
354 | The example above assumes that the traces to open are | |
355 | `LTTng <https://lttng.org/>`_ Linux kernel traces. | |
356 | ||
357 | Run this example: | |
358 | ||
359 | .. code-block:: text | |
360 | ||
361 | $ python3 example.py /path/to/one/or/more/lttng/traces | |
362 | ||
363 | Output example: | |
364 | ||
365 | .. code-block:: text | |
366 | ||
367 | CPU 2: Switching process `Timer` → `swapper/2` | |
368 | CPU 0: Switching process `swapper/0` → `firefox` | |
369 | CPU 0: Switching process `firefox` → `swapper/0` | |
370 | CPU 0: Switching process `swapper/0` → `rcu_preempt` | |
371 | CPU 0: Switching process `rcu_preempt` → `swapper/0` | |
372 | CPU 3: Switching process `swapper/3` → `alsa-sink-ALC26` | |
373 | CPU 2: Switching process `swapper/2` → `Timer` | |
374 | CPU 2: Switching process `Timer` → `swapper/2` | |
375 | CPU 2: Switching process `swapper/2` → `pulseaudio` | |
376 | CPU 0: Switching process `swapper/0` → `firefox` | |
377 | CPU 1: Switching process `swapper/1` → `threaded-ml` | |
378 | CPU 2: Switching process `pulseaudio` → `Timer` | |
379 | ||
380 | If you need to access a specific field, use: | |
381 | ||
382 | Event payload | |
383 | :attr:`bt2._EventConst.payload_field` property. | |
384 | ||
385 | Event specific context | |
386 | :attr:`bt2._EventConst.specific_context_field` property. | |
387 | ||
388 | Event common context | |
389 | :attr:`bt2._EventConst.common_context_field` property. | |
390 | ||
391 | Packet context | |
392 | :attr:`bt2._PacketConst.context_field` property. | |
393 | ||
394 | Use Python's ``in`` operator to verify if: | |
395 | ||
396 | A specific "root" field (in the list above) contains a given field by name | |
397 | .. code-block:: python | |
398 | ||
399 | if 'next_comm' in event.payload_field: | |
400 | # ... | |
401 | ||
402 | Any of the root fields contains a given field by name | |
403 | .. code-block:: python | |
404 | ||
405 | if 'next_comm' in event: | |
406 | # ... | |
407 | ||
408 | The following example iterates the events of a given trace, printing the | |
409 | value of the ``fd`` payload field if it's available:: | |
410 | ||
411 | import bt2 | |
412 | import sys | |
413 | ||
414 | # Create a trace collection message iterator from the first command-line | |
415 | # argument. | |
416 | msg_it = bt2.TraceCollectionMessageIterator(sys.argv[1]) | |
417 | ||
418 | # Iterate the trace messages. | |
419 | for msg in msg_it: | |
420 | # `bt2._EventMessageConst` is the Python type of an event message. | |
421 | if type(msg) is bt2._EventMessageConst: | |
422 | # Check if the `fd` event payload field exists. | |
423 | if 'fd' in msg.event.payload_field: | |
424 | # Print the `fd` event payload field's value. | |
425 | print(msg.event.payload_field['fd']) | |
426 | ||
427 | Output example: | |
428 | ||
429 | .. code-block:: text | |
430 | ||
431 | 14 | |
432 | 15 | |
433 | 16 | |
434 | 19 | |
435 | 30 | |
436 | 31 | |
437 | 33 | |
438 | 42 | |
439 | 0 | |
440 | 1 | |
441 | 2 | |
442 | 3 | |
443 | ||
444 | .. _examples_tcmi_ev_time: | |
445 | ||
446 | Get an event's time | |
447 | ~~~~~~~~~~~~~~~~~~~ | |
448 | The time, or timestamp, of an event object belongs to its message as | |
449 | a *default clock snapshot*. | |
450 | ||
451 | An event's clock snapshot is a *snapshot* (an immutable value) of the | |
452 | value of the event's stream's clock when the event occurred. As of | |
453 | Babeltrace |~| |version|, a stream can only have one clock: its default | |
454 | clock. | |
455 | ||
456 | Use the :attr:`default_clock_snapshot` property of an event message | |
457 | to get its default clock snapshot. A clock snapshot object offers, | |
458 | amongst other things, the following properties: | |
459 | ||
460 | :attr:`value` (:class:`int`) | |
461 | Value of the clock snapshot in clock cycles. | |
462 | ||
463 | A stream clock can have any frequency (Hz). | |
464 | ||
465 | :attr:`ns_from_origin` (:class:`int`) | |
466 | Number of nanoseconds from the stream clock's origin (often the Unix | |
467 | epoch). | |
468 | ||
469 | The following example prints, for each event, its name, its date/time, | |
470 | and the difference, in seconds, since the previous event's time (if | |
471 | any):: | |
472 | ||
473 | import bt2 | |
474 | import sys | |
475 | import datetime | |
476 | ||
477 | # Create a trace collection message iterator from the first command-line | |
478 | # argument. | |
479 | msg_it = bt2.TraceCollectionMessageIterator(sys.argv[1]) | |
480 | ||
481 | # Last event's time (ns from origin). | |
482 | last_event_ns_from_origin = None | |
483 | ||
484 | # Iterate the trace messages. | |
485 | for msg in msg_it: | |
486 | # `bt2._EventMessageConst` is the Python type of an event message. | |
487 | if type(msg) is bt2._EventMessageConst: | |
488 | # Get event message's default clock snapshot's ns from origin | |
489 | # value. | |
490 | ns_from_origin = msg.default_clock_snapshot.ns_from_origin | |
491 | ||
492 | # Compute the time difference since the last event message. | |
493 | diff_s = 0 | |
494 | ||
495 | if last_event_ns_from_origin is not None: | |
496 | diff_s = (ns_from_origin - last_event_ns_from_origin) / 1e9 | |
497 | ||
498 | # Create a `datetime.datetime` object from `ns_from_origin` for | |
499 | # presentation. Note that such an object is less accurate than | |
500 | # `ns_from_origin` as it holds microseconds, not nanoseconds. | |
501 | dt = datetime.datetime.fromtimestamp(ns_from_origin / 1e9) | |
502 | ||
503 | # Print line. | |
504 | fmt = '{} (+{:.6f} s): {}' | |
505 | print(fmt.format(dt, diff_s, msg.event.name)) | |
506 | ||
507 | # Update last event's time. | |
508 | last_event_ns_from_origin = ns_from_origin | |
509 | ||
510 | Run this example: | |
511 | ||
512 | .. code-block:: text | |
513 | ||
514 | $ python3 example.py /path/to/one/or/more/traces | |
515 | ||
516 | Output example: | |
517 | ||
518 | .. code-block:: text | |
519 | ||
520 | 2015-09-09 22:40:41.551451 (+0.000004 s): lttng_ust_statedump:end | |
521 | 2015-09-09 22:40:43.003397 (+1.451946 s): lttng_ust_dl:dlopen | |
522 | 2015-09-09 22:40:43.003412 (+0.000015 s): lttng_ust_dl:build_id | |
523 | 2015-09-09 22:40:43.003861 (+0.000449 s): lttng_ust_dl:dlopen | |
524 | 2015-09-09 22:40:43.003865 (+0.000004 s): lttng_ust_dl:build_id | |
525 | 2015-09-09 22:40:43.003879 (+0.000014 s): my_provider:my_first_tracepoint | |
526 | 2015-09-09 22:40:43.003895 (+0.000016 s): my_provider:my_first_tracepoint | |
527 | 2015-09-09 22:40:43.003898 (+0.000003 s): my_provider:my_other_tracepoint | |
528 | 2015-09-09 22:40:43.003922 (+0.000023 s): lttng_ust_dl:dlclose | |
529 | ||
530 | Bonus: Print top 5 running processes using LTTng | |
531 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
532 | As :ref:`examples_tcmi_ev_field` shows, a | |
533 | :class:`bt2.TraceCollectionMessageIterator` can read | |
534 | `LTTng <https://lttng.org/>`_ traces. | |
535 | ||
536 | The following example is similar to :ref:`examples_tcmi_ev_time`: it | |
537 | reads a whole LTTng Linux kernel trace, but instead of printing the time | |
538 | difference for each event, it accumulates them to print the short names | |
539 | of the top |~| 5 running processes on CPU |~| 0 during the whole trace. | |
540 | ||
541 | .. code-block:: python | |
542 | ||
543 | import bt2 | |
544 | import sys | |
545 | import collections | |
546 | ||
547 | # Create a trace collection message iterator from the first command-line | |
548 | # argument. | |
549 | msg_it = bt2.TraceCollectionMessageIterator(sys.argv[1]) | |
550 | ||
551 | # This counter dictionary will hold execution times: | |
552 | # | |
553 | # Task command name -> Total execution time (ns) | |
554 | exec_times = collections.Counter() | |
555 | ||
556 | # This holds the last `sched_switch` event time. | |
557 | last_ns_from_origin = None | |
558 | ||
559 | for msg in msg_it: | |
560 | # `bt2._EventMessageConst` is the Python type of an event message. | |
561 | # Only keep such messages. | |
562 | if type(msg) is not bt2._EventMessageConst: | |
563 | continue | |
564 | ||
565 | # An event message holds a trace event. | |
566 | event = msg.event | |
567 | ||
568 | # Only check `sched_switch` events. | |
569 | if event.name != 'sched_switch': | |
570 | continue | |
571 | ||
572 | # Keep only events which occurred on CPU 0. | |
573 | if event['cpu_id'] != 0: | |
574 | continue | |
575 | ||
576 | # Get event message's default clock snapshot's ns from origin value. | |
577 | ns_from_origin = msg.default_clock_snapshot.ns_from_origin | |
578 | ||
579 | if last_ns_from_origin is None: | |
580 | # We start here. | |
581 | last_ns_from_origin = ns_from_origin | |
582 | ||
583 | # Previous process's short name. | |
584 | prev_comm = str(event['prev_comm']) | |
585 | ||
586 | # Initialize an entry in our dictionary if not done yet. | |
587 | if prev_comm not in exec_times: | |
588 | exec_times[prev_comm] = 0 | |
589 | ||
590 | # Compute previous process's execution time. | |
591 | diff_ns = ns_from_origin - last_ns_from_origin | |
592 | ||
593 | # Update execution time of this command. | |
594 | exec_times[prev_comm] += diff_ns | |
595 | ||
596 | # Update last event's time. | |
597 | last_ns_from_origin = ns_from_origin | |
598 | ||
599 | # Print top 5. | |
600 | for comm, ns in exec_times.most_common(5): | |
601 | print('{:20}{} s'.format(comm, ns / 1e9)) | |
602 | ||
603 | Run this example: | |
604 | ||
605 | .. code-block:: text | |
606 | ||
607 | $ python3 example.py /path/to/lttng/trace | |
608 | ||
609 | Output example: | |
610 | ||
611 | .. code-block:: text | |
612 | ||
613 | swapper/0 326.294314471 s | |
614 | chromium 2.500456202 s | |
615 | Xorg.bin 0.546656895 s | |
616 | threaded-ml 0.545098185 s | |
617 | pulseaudio 0.53677713 s | |
618 | ||
619 | Note that ``swapper/0`` is the "idle" process of CPU |~| 0 on Linux; | |
620 | since we weren't using the CPU that much when tracing, its first | |
621 | position in the list makes sense. | |
622 | ||
623 | Inspect event classes | |
624 | ~~~~~~~~~~~~~~~~~~~~~ | |
625 | Each event stream is a *stream class* instance. | |
626 | ||
627 | A stream class contains *event classes*. A stream class's event classes | |
628 | describe all the possible events you can find in its instances. Stream | |
629 | classes and event classes form the *metadata* of streams and events. | |
630 | ||
631 | The following example shows how to list all the event classes of a | |
632 | stream class. For each event class, the example also prints the names of | |
633 | its payload field class's first-level members. | |
634 | ||
635 | .. note:: | |
636 | ||
637 | As of Babeltrace |~| |version|, there's no way to access a stream class | |
638 | without consuming at least one message for one of its instances | |
639 | (streams). | |
640 | ||
641 | A source component can add new event classes to existing stream | |
642 | classes during the trace processing task. Therefore, this example | |
643 | only lists the initial stream class's event classes. | |
644 | ||
645 | .. code-block:: python | |
646 | ||
647 | import bt2 | |
648 | import sys | |
649 | ||
650 | # Create a trace collection message iterator from the first command-line | |
651 | # argument. | |
652 | msg_it = bt2.TraceCollectionMessageIterator(sys.argv[1]) | |
653 | ||
654 | # Get the message iterator's first stream beginning message. | |
655 | for msg in msg_it: | |
656 | # `bt2._StreamBeginningMessageConst` is the Python type of a stream | |
657 | # beginning message. | |
658 | if type(msg) is bt2._StreamBeginningMessageConst: | |
659 | break | |
660 | ||
661 | # A stream beginning message holds a stream. | |
662 | stream = msg.stream | |
663 | ||
664 | # Get the stream's class. | |
665 | stream_class = stream.cls | |
666 | ||
667 | # The stream class object offers a mapping interface (like a read-only | |
668 | # `dict`), where keys are event class IDs and values are | |
669 | # `bt2._EventClassConst` objects. | |
670 | for event_class in stream_class.values(): | |
671 | print('{}:'.format(event_class.name)) | |
672 | ||
673 | # The `payload_field_class` property of an event class returns a | |
674 | # `bt2._StructureFieldClassConst` object. This object offers a | |
675 | # mapping interface, where keys are member names and values are | |
676 | # `bt2._StructureFieldClassMemberConst` objects. | |
677 | for member in event_class.payload_field_class.values(): | |
678 | fmt = ' {}: `{}.{}`' | |
679 | print(fmt.format(member.name, bt2.__name__, | |
680 | member.field_class.__class__.__name__)) | |
681 | ||
682 | Run this example: | |
683 | ||
684 | .. code-block:: text | |
685 | ||
686 | $ python3 example.py /path/to/trace | |
687 | ||
688 | Output example: | |
689 | ||
690 | .. code-block:: text | |
691 | ||
692 | sched_migrate_task: | |
693 | comm: `bt2._StringFieldClassConst` | |
694 | tid: `bt2._SignedIntegerFieldClassConst` | |
695 | prio: `bt2._SignedIntegerFieldClassConst` | |
696 | orig_cpu: `bt2._SignedIntegerFieldClassConst` | |
697 | dest_cpu: `bt2._SignedIntegerFieldClassConst` | |
698 | sched_switch: | |
699 | prev_comm: `bt2._StringFieldClassConst` | |
700 | prev_tid: `bt2._SignedIntegerFieldClassConst` | |
701 | prev_prio: `bt2._SignedIntegerFieldClassConst` | |
702 | prev_state: `bt2._SignedIntegerFieldClassConst` | |
703 | next_comm: `bt2._StringFieldClassConst` | |
704 | next_tid: `bt2._SignedIntegerFieldClassConst` | |
705 | next_prio: `bt2._SignedIntegerFieldClassConst` | |
706 | sched_wakeup_new: | |
707 | comm: `bt2._StringFieldClassConst` | |
708 | tid: `bt2._SignedIntegerFieldClassConst` | |
709 | prio: `bt2._SignedIntegerFieldClassConst` | |
710 | target_cpu: `bt2._SignedIntegerFieldClassConst` | |
711 | ||
712 | .. _examples_graph: | |
713 | ||
714 | Build and run a trace processing graph | |
715 | -------------------------------------- | |
716 | Internally, a :class:`bt2.TraceCollectionMessageIterator` object (see | |
717 | :ref:`examples_tcmi`) builds a *trace processing graph*, just like the | |
718 | :bt2man:`babeltrace2-convert(1)` CLI command, and then offers a | |
719 | Python iterator interface on top of it. | |
720 | ||
721 | See the :bt2man:`babeltrace2-intro(7)` manual page to learn more about | |
722 | the Babeltrace |~| 2 project and its core concepts. | |
723 | ||
724 | The following examples shows how to manually build and then run a trace | |
725 | processing graph yourself (like the :bt2man:`babeltrace2-run(1)` CLI | |
726 | command does). The general steps to do so are: | |
727 | ||
728 | #. Create an empty graph. | |
729 | ||
730 | #. Add components to the graph. | |
731 | ||
732 | This process is also known as *instantiating a component class* | |
733 | because the graph must first create the component from its class | |
734 | before adding it. | |
735 | ||
736 | A viable graph contains at least one source component and one sink | |
737 | component. | |
738 | ||
739 | #. Connect component ports. | |
740 | ||
741 | On initialization, components add input and output ports, depending | |
742 | on their type. | |
743 | ||
744 | You can connect component output ports to input ports within a graph. | |
745 | ||
746 | #. Run the graph. | |
747 | ||
748 | This is a blocking operation which makes each sink component consume | |
749 | some messages in a round robin fashion until there are no more. | |
750 | ||
751 | .. code-block:: python | |
752 | ||
753 | import bt2 | |
754 | import sys | |
755 | ||
756 | # Create an empty graph. | |
757 | graph = bt2.Graph() | |
758 | ||
759 | # Add a `source.text.dmesg` component. | |
760 | # | |
761 | # graph.add_component() returns the created and added component. | |
762 | # | |
763 | # Such a component reads Linux kernel ring buffer messages (see | |
764 | # `dmesg(1)`) from the standard input and creates corresponding event | |
765 | # messages. See `babeltrace2-source.text.dmesg(7)`. | |
766 | # | |
767 | # `my source` is the unique name of this component within `graph`. | |
768 | comp_cls = bt2.find_plugin('text').source_component_classes['dmesg'] | |
769 | src_comp = graph.add_component(comp_cls, 'my source') | |
770 | ||
771 | # Add a `sink.text.pretty` component. | |
772 | # | |
773 | # Such a component pretty-prints event messages on the standard output | |
774 | # (one message per line). See `babeltrace2-sink.text.pretty(7)`. | |
775 | # | |
776 | # The `babeltrace2 convert` CLI command uses a `sink.text.pretty` | |
777 | # sink component by default. | |
778 | comp_cls = bt2.find_plugin('text').sink_component_classes['pretty'] | |
779 | sink_comp = graph.add_component(comp_cls, 'my sink') | |
780 | ||
781 | # Connect the `out` output port of the `source.text.dmesg` component | |
782 | # to the `in` input port of the `sink.text.pretty` component. | |
783 | graph.connect_ports(src_comp.output_ports['out'], | |
784 | sink_comp.input_ports['in']) | |
785 | ||
786 | # Run the trace processing graph. | |
787 | graph.run() | |
788 | ||
789 | Run this example: | |
790 | ||
791 | .. code-block:: text | |
792 | ||
793 | $ dmesg -t | python3 example.py | |
794 | ||
795 | Output example: | |
796 | ||
797 | .. code-block:: text | |
798 | ||
799 | string: { str = "ata1.00: NCQ Send/Recv Log not supported" } | |
800 | string: { str = "ata1.00: ACPI cmd ef/02:00:00:00:00:a0 (SET FEATURES) succeeded" } | |
801 | string: { str = "ata1.00: ACPI cmd f5/00:00:00:00:00:a0 (SECURITY FREEZE LOCK) filtered out" } | |
802 | string: { str = "ata1.00: ACPI cmd ef/10:03:00:00:00:a0 (SET FEATURES) filtered out" } | |
803 | string: { str = "ata1.00: NCQ Send/Recv Log not supported" } | |
804 | string: { str = "ata1.00: configured for UDMA/133" } | |
805 | string: { str = "ata1.00: Enabling discard_zeroes_data" } | |
806 | string: { str = "OOM killer enabled." } | |
807 | string: { str = "Restarting tasks ... done." } | |
808 | string: { str = "PM: suspend exit" } | |
809 | ||
810 | Query a component class | |
811 | ----------------------- | |
812 | Component classes, provided by plugins, can implement a method to | |
813 | support *query operations*. | |
814 | ||
815 | A query operation is similar to a function call: the caller makes a | |
816 | request (a query) with parameters and the component class's query | |
817 | method returns a result object. | |
818 | ||
819 | The query operation feature exists so that you can benefit from a | |
820 | component class's implementation to get information about a trace, a | |
821 | stream, a distant server, and so on. For example, the | |
822 | ``source.ctf.lttng-live`` component class (see | |
823 | :bt2man:`babeltrace2-source.ctf.lttng-live(7)`) offers the ``sessions`` | |
824 | object to list the available | |
ec3bf3f1 | 825 | `LTTng live <https://lttng.org/docs/#doc-lttng-live>`_ tracing |
ba64dfcc SM |
826 | session names and other properties. |
827 | ||
828 | The semantics of the query parameters and the returned object are | |
829 | completely defined by the component class implementation: the library | |
830 | and its Python bindings don't enforce or suggest any layout. | |
831 | The best way to know which objects you can query from a component class, | |
832 | what are the expected and optional parameters, and what the returned | |
833 | object contains is to read this component class's documentation. | |
834 | ||
835 | The following example queries the "standard" ``babeltrace.support-info`` | |
836 | query object (see | |
837 | :bt2man:`babeltrace2-query-babeltrace.support-info(7)`) from the | |
838 | ``source.ctf.fs`` component class | |
839 | (see :bt2man:`babeltrace2-source.ctf.fs(7)`) and | |
840 | pretty-prints the result. The ``babeltrace.support-info`` query object | |
841 | indicates whether or not a given path locates a | |
842 | :abbr:`CTF (Common Trace Format)` trace directory:: | |
843 | ||
844 | import bt2 | |
845 | import sys | |
846 | ||
847 | # Get the `source.ctf.fs` component class from the `ctf` plugin. | |
848 | comp_cls = bt2.find_plugin('ctf').source_component_classes['fs'] | |
849 | ||
850 | # The `babeltrace.support-info` query operation expects a `type` | |
851 | # parameter (set to `directory` here) and an `input` parameter (the | |
852 | # actual path or string to check, in this case the first command-line | |
853 | # argument). | |
854 | # | |
855 | # See `babeltrace2-query-babeltrace.support-info(7)`. | |
856 | params = { | |
857 | 'type': 'directory', | |
858 | 'input': sys.argv[1], | |
859 | } | |
860 | ||
861 | # Create a query executor. | |
862 | # | |
863 | # This is the environment in which query operations happens. The | |
864 | # queried component class has access to this executor, for example to | |
865 | # retrieve the query operation's logging level. | |
866 | query_exec = bt2.QueryExecutor(comp_cls, 'babeltrace.support-info', | |
867 | params) | |
868 | ||
869 | # Query the component class through the query executor. | |
870 | # | |
871 | # This method returns the result. | |
872 | result = query_exec.query() | |
873 | ||
874 | # Print the result. | |
875 | print(result) | |
876 | ||
877 | As you can see, no trace processing graph is involved (like in | |
878 | :ref:`examples_tcmi` and :ref:`examples_graph`): a query operation | |
879 | is *not* a sequential trace processing task, but a simple, atomic | |
880 | procedure call. | |
881 | ||
882 | Run this example: | |
883 | ||
884 | .. code-block:: text | |
885 | ||
886 | $ python3 example.py /path/to/ctf/trace | |
887 | ||
888 | Output example: | |
889 | ||
890 | .. code-block:: text | |
891 | ||
892 | {'group': '21c63a42-40bc-4c08-9761-3815ae01f43d', 'weight': 0.75} | |
893 | ||
894 | This result indicates that the component class is 75 |~| % confident that | |
895 | :file:`/path/to/ctf/trace` is a CTF trace directory path. It also shows | |
896 | that this specific CTF trace belongs to the | |
897 | ``21c63a42-40bc-4c08-9761-3815ae01f43d`` group; a single component can | |
898 | handle multiple traces which belong to the same group. | |
899 | ||
900 | Let's try the sample example with a path that doesn't locate a CTF | |
901 | trace: | |
902 | ||
903 | .. code-block:: text | |
904 | ||
905 | $ python3 example.py /etc | |
906 | ||
907 | Output: | |
908 | ||
909 | .. code-block:: text | |
910 | ||
911 | {'weight': 0.0} | |
912 | ||
913 | As expected, the zero weight indicates that ``/etc`` isn't a CTF trace | |
914 | directory path. |