2. Reader API

The classes documented below are related to reading traces operations. Common operations such as adding traces to a trace collection, iterating on their events, reading event names, timestamps, contexts and payloads can be accomplished by using these classes.

The Babeltrace Python bindings’ reader API exposes two categories of classes. The first category is used to open traces and iterate on theirs events. The typical procedure for reading traces is:

  1. Create a TraceCollection instance.
  2. Add traces to this collection using TraceCollection.add_trace().
  3. Iterate on TraceCollection.events to get Event objects and perform the desired computation on event data.

See also

Reader API examples

class babeltrace.reader.TraceCollection

A collection of opened traces.

class babeltrace.reader.TraceHandle

A trace handle. Allows the user to manipulate a specific trace directly.

class babeltrace.reader.Event

An event.

exception babeltrace.reader.FieldError

A field error. Raised when a field’s value cannot be accessed.

The second category of classes is a set of declaration classes that are returned when inspecting the layout of a trace’s events, through TraceHandle.events. The following classes are not meant to be instantiated by the user:

class babeltrace.reader.EventDeclaration

Event declaration.

class babeltrace.reader.FieldDeclaration

Event field declaration (base class for all the following types).

class babeltrace.reader.IntegerFieldDeclaration

Integer field declaration.

class babeltrace.reader.FloatFieldDeclaration

Floating point number field declaration.

class babeltrace.reader.EnumerationFieldDeclaration

Enumeration field declaration.

class babeltrace.reader.StringFieldDeclaration

String (NULL-terminated array of bytes) field declaration.

class babeltrace.reader.ArrayFieldDeclaration

Static array field declaration.

class babeltrace.reader.SequenceFieldDeclaration

Sequence (dynamic array) field declaration.

class babeltrace.reader.StructureFieldDeclaration

Structure field declaration. A structure is an ordered map of field names to field values.

class babeltrace.reader.VariantFieldDeclaration

Variant field declaration. A variant is dynamic selection between different types.

Here is the subclass relationship for the reader API:

object
    TraceCollection
    TraceHandle
    Event
    FieldError
    EventDeclaration
    FieldDeclaration
        IntegerFieldDeclaration
        FloatFieldDeclaration
        EnumerationFieldDeclaration
        StringFieldDeclaration
        ArrayFieldDeclaration
        SequenceFieldDeclaration
        StructureFieldDeclaration
        VariantFieldDeclaration

2.1. TraceCollection

class babeltrace.reader.TraceCollection(intersect_mode=False)

A TraceCollection is a collection of opened traces.

Once a trace collection is created, you can add traces to the collection by using the add_trace() or add_traces_recursive(), and then iterate on the merged events using events.

You may use remove_trace() to close and remove a specific trace from a trace collection.

__init__(intersect_mode=False)

Creates an empty trace collection.

add_trace(path, format_str)

Adds a trace to the trace collection.

path is the exact path of the trace on the filesystem.

format_str is a string indicating the type of trace to add. ctf is currently the only supported trace format.

Returns the corresponding TraceHandle instance for this opened trace on success, or None on error.

This function does not recurse directories to find a trace. See add_traces_recursive() for a recursive version of this function.

add_traces_recursive(path, format_str)

Adds traces to this trace collection by recursively searching in the path directory.

format_str is a string indicating the type of trace to add. ctf is currently the only supported trace format.

Returns a dict object mapping full paths to trace handles for each trace found, or None on error.

See also add_trace().

events

Generates the ordered Event objects of all the opened traces contained in this trace collection.

Due to limitations of the native Babeltrace API, only one event may be “alive” at a given time, i.e. a user should never store a copy of the events returned by this function for ulterior use. Users shall make sure to copy the information they need from an event before accessing the next one.

events_timestamps(timestamp_begin, timestamp_end)

Generates the ordered Event objects of all the opened traces contained in this trace collection from timestamp_begin to timestamp_end.

timestamp_begin and timestamp_end are given in nanoseconds since Epoch.

See events for notes and limitations.

remove_trace(trace_handle)

Removes a trace from the trace collection using its trace handle trace_handle.

TraceHandle objects are returned by add_trace() and add_traces_recursive().

timestamp_begin

Begin timestamp of this trace collection (nanoseconds since Epoch).

timestamp_end

End timestamp of this trace collection (nanoseconds since Epoch).

2.2. TraceHandle

class babeltrace.reader.TraceHandle

A TraceHandle is a handle allowing the user to manipulate a specific trace directly. It is a unique identifier representing a trace, and is not meant to be instantiated by the user.

events

Generates all the EventDeclaration objects of the underlying trace.

id

Numeric ID of this trace handle.

path

Path of the underlying trace.

timestamp_begin

Buffers creation timestamp (nanoseconds since Epoch) of the underlying trace.

timestamp_end

Buffers destruction timestamp (nanoseconds since Epoch) of the underlying trace.

2.3. Event

class babeltrace.reader.Event

An Event object represents a trace event. Event objects are returned by TraceCollection.events and are not meant to be instantiated by the user.

Event has a dict-like interface for accessing an event’s field value by field name:

event['my_field']

If a field name exists in multiple scopes, the value of the first field found is returned. The scopes are searched in the following order:

  1. Event fields (babeltrace.common.CTFScope.EVENT_FIELDS)
  2. Event context (babeltrace.common.CTFScope.EVENT_CONTEXT)
  3. Stream event context (babeltrace.common.CTFScope.STREAM_EVENT_CONTEXT)
  4. Event header (babeltrace.common.CTFScope.STREAM_EVENT_HEADER)
  5. Packet context (babeltrace.common.CTFScope.STREAM_PACKET_CONTEXT)
  6. Packet header (babeltrace.common.CTFScope.TRACE_PACKET_HEADER)

It is still possible to obtain a field’s value from a specific scope using field_with_scope().

Field values are returned as native Python types, that is:

Field type Python type
Integer int
Floating point number float
Enumeration str (enumeration label)
String str
Array list of native Python objects
Sequence list of native Python objects
Structure dict mapping field names to native Python objects

For example, printing the third element of a sequence named seq in a structure named my_struct of the event’s field named my_field is done this way:

print(event['my_field']['my_struct']['seq'][2])
cycles

Event timestamp in cycles or -1 on error.

datetime

Event timestamp as a standard datetime.datetime object.

Note that the datetime.datetime class’ precision is limited to microseconds, whereas timestamp provides the event’s timestamp with a nanosecond resolution.

field_list_with_scope(scope)

Returns a list of field names in the scope scope.

field_with_scope(field_name, scope)

Returns the value of a field named field_name within the scope scope, or None if the field cannot be found.

scope must be one of babeltrace.common.CTFScope constants.

get(field_name, default=None)

Returns the value of the field named field_name, or default when not found.

See Event note about how fields are retrieved by name when multiple fields share the same name in different scopes.

handle

TraceHandle object containing this event, or None on error.

items()

Generates pairs of (field name, field value).

This method iterates keys() to find field names, which means some fields could be unavailable if other fields share their names in scopes with higher priorities.

keys()

Returns the list of field names.

Note: field names are unique within the returned list, although a field name could exist in multiple scopes. Use field_list_with_scope() to obtain the list of field names of a given scope.

name

Event name or None on error.

timestamp

Event timestamp (nanoseconds since Epoch).

trace_collection

TraceCollection object containing this event, or None on error.

2.4. FieldError

exception babeltrace.reader.FieldError(value)

Field error, raised when the value of a field cannot be accessed.

2.5. EventDeclaration

class babeltrace.reader.EventDeclaration

An event declaration contains the properties of a class of events, that is, the common properties and fields layout of all the actual recorded events associated with this declaration.

This class is not meant to be instantiated by the user. It is returned by TraceHandle.events.

fields

Generates all the field declarations of this event, going through each scope in the following order:

  1. Event fields (babeltrace.common.CTFScope.EVENT_FIELDS)
  2. Event context (babeltrace.common.CTFScope.EVENT_CONTEXT)
  3. Stream event context (babeltrace.common.CTFScope.STREAM_EVENT_CONTEXT)
  4. Event header (babeltrace.common.CTFScope.STREAM_EVENT_HEADER)
  5. Packet context (babeltrace.common.CTFScope.STREAM_PACKET_CONTEXT)
  6. Packet header (babeltrace.common.CTFScope.TRACE_PACKET_HEADER)

All the generated field declarations inherit FieldDeclaration, and are among:

fields_scope(scope)

Generates all the field declarations of the event’s scope scope.

scope must be one of babeltrace.common.CTFScope constants.

All the generated field declarations inherit FieldDeclaration, and are among:

id

Event numeric ID, or -1 on error.

name

Event name, or None on error.

2.6. FieldDeclaration

class babeltrace.reader.FieldDeclaration

Base class for concrete field declarations.

This class is not meant to be instantiated by the user.

name

Field name, or None on error.

scope

Field scope (one of:class:babeltrace.common.CTFScope constants).

type

Field type (one of babeltrace.common.CTFTypeId constants).

2.7. IntegerFieldDeclaration

class babeltrace.reader.IntegerFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

Integer field declaration.

base

Integer base (int), or a negative value on error.

byte_order

Integer byte order (one of babeltrace.common.ByteOrder constants).

encoding

Integer encoding (one of babeltrace.common.CTFStringEncoding constants).

signedness

0 if this integer is unsigned, 1 if signed, or -1 on error.

size

Integer size in bits, or a negative value on error.

2.8. FloatFieldDeclaration

class babeltrace.reader.FloatFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

Floating point number field declaration.

Note

As of this version, this class is missing some properties.

2.9. EnumerationFieldDeclaration

class babeltrace.reader.EnumerationFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

Enumeration field declaration.

Note

As of this version, this class is missing some properties.

2.10. StringFieldDeclaration

class babeltrace.reader.StringFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

String (NULL-terminated array of bytes) field declaration.

Note

As of this version, this class is missing some properties.

2.11. ArrayFieldDeclaration

class babeltrace.reader.ArrayFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

Static array field declaration.

element_declaration

Field declaration of the underlying element.

length

Fixed length of this static array (number of contained elements), or a negative value on error.

2.12. SequenceFieldDeclaration

class babeltrace.reader.SequenceFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

Sequence (dynamic array) field declaration.

Note

As of this version, this class is missing some properties.

element_declaration

Field declaration of the underlying element.

2.13. StructureFieldDeclaration

class babeltrace.reader.StructureFieldDeclaration

Bases: babeltrace.reader.FieldDeclaration

Structure (ordered map of field names to field declarations) field declaration.

Note

As of this version, this class is missing some properties.

2.14. VariantFieldDeclaration

class babeltrace.reader.VariantFieldDeclaration

Variant (dynamic selection between different types) field declaration.

Note

As of this version, this class is missing some properties.