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