4. Examples¶

This section presents a few short and straightforward examples of Babeltrace Python bindings usage.

The examples are divided into two categories: those which demonstrate the reader API, and those which demonstrate the CTF writer API.

4.1. Reader API examples¶

The reader API includes everything needed to open traces and iterate on events in order.

4.1.1. Open one trace and print all event names¶

This example shows how to open a single CTF trace, iterate on all the events, and print their names.

import babeltrace.reader
import sys


# get the trace path from the first command line argument
trace_path = sys.argv[1]

trace_collection = babeltrace.reader.TraceCollection()

trace_collection.add_trace(trace_path, 'ctf')

for event in trace_collection.events:
    print(event.name)

4.1.2. Open multiple traces and print all event field names¶

This example opens multiple CTF traces (their paths are provided as command line arguments), iterates on all their correlated events in order, and prints a list of their field names.

import babeltrace.reader
import sys


trace_collection = babeltrace.reader.TraceCollection()

for path in sys.argv[1:]:
    trace_collection.add_trace(path, 'ctf')

for event in trace_collection.events:
    print(', '.join(event.keys()))

4.1.3. Print a specific event field¶

Reading the field value of an babeltrace.reader.Event object is done by using its dict-like interface:

field_value = event['field_name']

As such, you can use Python’s in keyword to verify if a given event contains a given field name:

if 'field_name' in event:
    # ...

The following example iterates on the events of a trace, and prints the value of the fd field if it’s available.

import babeltrace.reader
import sys

# get the trace path from the first command line argument
trace_path = sys.argv[1]

trace_collection = babeltrace.reader.TraceCollection()

trace_collection.add_trace(trace_path, 'ctf')

for event in trace_collection.events:
    if 'fd' in event:
        print(event['fd'])

Beware that different fields of the same event may share the same name if they are in different scopes. In this case, the dict-like interface prioritizes event payload fields before event context fields, event context fields before stream event context fields, and so on (see babeltrace.reader.Event for this exact list of priorities). It is possible to get the value of an event’s field within a specific scope using babeltrace.reader.Event.field_with_scope():

import babeltrace.reader
import babeltrace.common

# ...

field_value = event.field_with_scope('field_name',
                                     babeltrace.common.CTFScope.EVENT_CONTEXT)

4.1.4. Bonus: top 5 running processes using LTTng¶

Since LTTng produces CTF traces, the Babeltrace Python binding can read LTTng traces.

This somewhat more complex example reads a whole LTTng Linux kernel trace, and outputs the short names of the top 5 running processes on CPU 0 during the whole trace.

from collections import Counter
import babeltrace.reader
import sys


# a trace collection holds one or more traces
col = babeltrace.reader.TraceCollection()

# add the trace provided by the user (first command line argument)
# (LTTng traces always have the 'ctf' format)
if col.add_trace(sys.argv[1], 'ctf') is None:
    raise RuntimeError('Cannot add trace')

# this counter dict will hold execution times:
#
#   task command name -> total execution time (ns)
exec_times = Counter()

# this holds the last `sched_switch` timestamp
last_ts = None

# iterate on events
for event in col.events:
    # keep only `sched_switch` events
    if event.name != 'sched_switch':
        continue

    # keep only events which happened on CPU 0
    if event['cpu_id'] != 0:
        continue

    # event timestamp
    cur_ts = event.timestamp

    if last_ts is None:
        # we start here
        last_ts = cur_ts

    # previous task command (short) name
    prev_comm = event['prev_comm']

    # initialize entry in our dict if not yet done
    if prev_comm not in exec_times:
        exec_times[prev_comm] = 0

    # compute previous command execution time
    diff = cur_ts - last_ts

    # update execution time of this command
    exec_times[prev_comm] += diff

    # update last timestamp
    last_ts = cur_ts

# print top 5
for name, ns in exec_times.most_common(5):
    s = ns / 1000000000
    print('{:20}{} s'.format(name, s))

4.1.5. Inspect event declarations and their field declarations¶

When babeltrace.reader.TraceCollection.add_trace() is called and a trace is successfully opened and added, a corresponding babeltrace.reader.TraceHandle object for this trace is returned. It is then possible to iterate on the event declarations of this trace handle using babeltrace.reader.TraceHandle.events. Each generated babeltrace.reader.EventDeclaration object contains common properties for this type of event, including its field declarations. This is useful for inspecting the available events of a trace, and their “signature” in terms of fields, before iterating its actual events.

This example adds a trace to a trace collection, and uses the returned trace handle to iterate on its event declarations. The goal here is to make sure the sched_switch event exists, and that it contains at least the following fields:

prev_comm, which should be an array of 8-bit integers
prev_tid, which should be an integer

import babeltrace.reader as btr
import sys


def validate_sched_switch_fields(event_decl):
    found_prev_comm = False
    found_prev_tid = False

    for field_decl in event_decl.fields:
        if field_decl.name == 'prev_comm':
            if isinstance(field_decl, btr.ArrayFieldDeclaration):
                elem_decl = field_decl.element_declaration

                if isinstance(elem_decl, btr.IntegerFieldDeclaration):
                    if elem_decl.size == 8:
                        found_prev_comm = True
        elif field_decl.name == 'prev_tid':
            if isinstance(field_decl, btr.IntegerFieldDeclaration):
                found_prev_tid = True

    return found_prev_comm and found_prev_tid


# get the trace path from the first command line argument
trace_path = sys.argv[1]

trace_collection = btr.TraceCollection()
trace_handle = trace_collection.add_trace(trace_path, 'ctf')
sched_switch_found = False

for event_decl in trace_handle.events:
    if event_decl.name == 'sched_switch':
        if validate_sched_switch_fields(event_decl):
            sched_switch_found = True
            break

print('trace path: {}'.format(trace_handle.path))

if sched_switch_found:
    print('found sched_switch!')
else:
    print('could not find sched_switch')

4.2. CTF writer API examples¶

The CTF writer API is a set of classes which allows a Python script to write complete CTF (Common Trace Format) traces.

4.2.1. One trace, one stream, one event, one field¶

This is the most simple example of using the CTF writer API. It creates one writer (responsible for writing one trace), then uses it to create one stream. One event with a single field is appended to this single stream, and everything is flushed.