3. CTF writer API

The CTF writer API allows to write native CTF traces from a Python environment.

A CTF trace is made of one or more CTF streams. Streams contain packets, which in turn contain serialized events. CTF readers, such as Babeltrace, are able to merge streams and iterate on events in order when reading a CTF trace.

The CTF writer API is exposed as a set of classes available in the babeltrace.writer module.

See also

CTF writer API examples

There is a clear distinction to be made between field declaration and field objects. A field declaration describes the properties, or metadata, of a field. It does not contain a value. For example, an integer field declaration contains a size in bits, a byte order, a display base, whether it’s signed or not, and so on. On the other hand, an integer field is linked with a specific integer field declaration, but contains an actual integer value. Thus, the layout and properties of fields are described once in field declarations, and then all concrete fields carry a value and a field declaration reference. The same applies to event classes vs. events, as well as to stream classes vs. streams.

The main interface to write a CTF trace is the Writer class:

class babeltrace.writer.Writer

Writing object in which clocks and streams may be registered, and other common trace properties may be set.

A concrete Stream object may be created from a StreamClass using Writer.create_stream() method. A stream class is also associated with a clock (Clock), which must also be registered to the writer object.

class babeltrace.writer.StreamClass

Stream class.

class babeltrace.writer.Stream

Stream, based on a stream class.

class babeltrace.writer.Clock

Reference clock of one to many streams.

Events, before being created, must be described in an event class (EventClass). An event class must be added to a stream class using StreamClass.add_event_class() before appending an event to an actual stream linked with this stream class.

class babeltrace.writer.EventClass

Event class.

class babeltrace.writer.Event

Event, based on an event class.

An event class is created by instantiating an EventClass object and using its add_field() method to add an instance of one of the following field declarations:

class babeltrace.writer.IntegerFieldDeclaration

Integer field declaration.

class babeltrace.writer.FloatingPointFieldDeclaration

Floating point number field declaration.

class babeltrace.writer.EnumerationFieldDeclaration

Enumeration field declaration (mapping from labels to ranges of integers).

class babeltrace.writer.StringFieldDeclaration

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

class babeltrace.writer.ArrayFieldDeclaration

Static array field declaration.

class babeltrace.writer.SequenceFieldDeclaration

Sequence (dynamic array) field declaration.

class babeltrace.writer.StructureFieldDeclaration

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

class babeltrace.writer.VariantFieldDeclaration

Variant (dynamic selection between different field declarations) field declaration.

Once an event class is created, a concrete event may be created by instantiating an Event object. Its payload() method may be used to access the actual event’s fields and set their values. Those fields are instances of the following types:

class babeltrace.writer.IntegerField

Integer field.

class babeltrace.writer.FloatingPointField

Floating point number field.

class babeltrace.writer.EnumerationField

Enumeration field (mapping from labels to ranges of integers).

class babeltrace.writer.StringField

String (NULL-terminated array of bytes) field.

class babeltrace.writer.ArrayField

Static array field.

class babeltrace.writer.SequenceField

Sequence (dynamic array) field.

class babeltrace.writer.StructureField

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

class babeltrace.writer.VariantField

Variant (dynamic selection between different field declarations) field.

The subclass relationship for the CTF writer API is the following:

object
    FieldDeclaration
        IntegerFieldDeclaration
        FloatingPointFieldDeclaration
        EnumerationFieldDeclaration
        StringFieldDeclaration
        ArrayFieldDeclaration
        SequenceFieldDeclaration
        StructureFieldDeclaration
        VariantFieldDeclaration
    Field
        IntegerField
        FloatingPointField
        EnumerationField
        StringField
        ArrayField
        SequenceField
        StructureField
        VariantField
    EnumerationMapping
    EventClass
    Event
    Clock
    StreamClass
    Stream
    Writer

Most of these classes’ methods and properties raise ValueError on error.

3.1. Writer

class babeltrace.writer.Writer(path)

This object is the CTF writer API context. It oversees its streams and clocks, and is responsible for writing one CTF trace.

__init__(path)

Creates a CTF writer, initializing a new CTF trace at path path.

path must be an existing directory, since a CTF trace is made of multiple files.

ValueError is raised if the creation fails.

add_clock(clock)

Registers Clock object clock to the writer.

You must register CTF clocks assigned to stream classes to the writer.

ValueError is raised if the creation fails.

add_environment_field(name, value)

Sets the CTF environment variable named name to value value (converted to a string).

ValueError is raised on error.

byte_order

Native byte order of this trace (one of babeltrace.common.ByteOrder constants).

This is the actual byte order that is used when a field declaration has the babeltrace.common.ByteOrder.BYTE_ORDER_NATIVE value.

Set this attribute to change the trace’s native byte order.

Defaults to the host machine’s endianness.

ValueError is raised on error.

create_stream(stream_class)

Creates and registers a new stream based on stream class stream_class.

This is the standard way of creating a Stream object: the user is not allowed to instantiate this class.

Returns a new Stream object.

flush_metadata()

Flushes the trace’s metadata to the metadata file.

metadata

Current metadata of this trace (str).

3.2. StreamClass

class babeltrace.writer.StreamClass(name)

A stream class contains the properties of specific streams (Stream). Any concrete stream must be linked with a StreamClass, usually by calling Writer.create_stream().

Some attributes are automatically set when creating a stream class. For example, if no clock is explicitly set using the clock attribute, a default clock will be created when needed.

__init__(name)

Creates a stream class named name.

ValueError is raised on error.

add_event_class(event_class)

Registers the EventClass event_class to this stream class.

Once the event class is registered, it will be generated as one of the event classes generated by event_classes.

ValueError is raised on error.

clock

Stream class’ clock (Clock object).

Set this attribute to change the clock of this stream class.

ValueError is raised on error.

event_classes

Generates the event classes (EventClass objects) of this stream class.

TypeError is raised on error.

id

Stream class’ numeric ID.

Set this attribute to change the ID of this stream class.

ValueError is raised on error.

name

Stream class’ name.

TypeError is raised on error.

packet_context_type

Stream packet context declaration.

Set this attribute to change the stream packet context declaration (must be an instance of StructureFieldDeclaration).

ValueError is raised on error.

3.3. Stream

class babeltrace.writer.Stream

Streams are specific instances of stream classes, which means they may contain actual, concrete events.

Stream objects are returned by Writer.create_stream(); they are not meant to be instantiated by the user.

Concrete Event objects are appended to Stream objects using append_event().

When flush() is called, a CTF packet is created, containing all the appended events since the last flush. Although the stream is flushed on object destruction, it is strongly recommended that the user call flush() manually before exiting the script, as __del__() is not always reliable.

append_discarded_events(event_count)

Appends event_count discarded events to this stream.

append_event(event)

Appends event event (Event object) to this stream.

The stream’s associated clock will be sampled during this call. event shall not be modified after being appended to this stream.

ValueError is raised on error.

discarded_events

Number of discarded (lost) events in this stream so far.

ValueError is raised on error.

flush()

Flushes the current packet of this stream to disk. Events subsequently appended to the stream will be added to a new packet.

ValueError is raised on error.

packet_context

Stream packet context field (instance of StructureField).

Set this attribute to assign a stream packet context field to this stream.

ValueError is raised on error.

3.4. Clock

class babeltrace.writer.Clock(name)

A CTF clock allows the description of the system’s clock topology, as well as the definition of each clock’s parameters.

Clock objects must be registered to a Writer object (see Writer.add_clock()), as well as be registered to a StreamClass object (see StreamClass.clock).

__init__(name)

Creates a default CTF clock named name.

ValueError is raised on error.

absolute

True if this clock is absolute, i.e. if the clock is a global reference across the other clocks of the trace.

Set this attribute to change the clock’s absolute state (boolean).

ValueError is raised on error.

description

Clock description (string).

Set this attribute to change the clock’s description.

ValueError is raised on error.

frequency

Clock frequency in Hz (integer).

Set this attribute to change the clock’s frequency.

ValueError is raised on error.

name

Clock name.

Set this attribute to change the clock’s name.

ValueError is raised on error.

offset

Clock offset in ticks since (POSIX.1 Epoch + offset_seconds).

Set this attribute to change the clock’s offset.

ValueError is raised on error.

offset_seconds

Clock offset in seconds since POSIX.1 Epoch (integer).

Set this attribute to change the clock’s offset in seconds.

ValueError is raised on error.

precision

Clock precision in clock ticks (integer).

Set this attribute to change the clock’s precision.

ValueError is raised on error.

time

Clock current time; nanoseconds (integer) since clock origin (POSIX.1 Epoch + offset_seconds + offset).

Set this attribute to change the clock’s current time.

ValueError is raised on error.

uuid

Clock UUID (an uuid.UUID object).

Set this attribute to change the clock’s UUID.

ValueError is raised on error.

3.5. EventClass

class babeltrace.writer.EventClass(name)

An event class contains the properties of specific events (Event). Any concrete event must be linked with an EventClass.

Some attributes are automatically set when creating an event class. For example, if no numeric ID is explicitly set using the id attribute, a default, unique ID within the stream class containing this event class will be created when needed.

__init__(name)

Creates an event class named name.

ValueError is raised on error.

add_field(field_type, field_name)

Adds a field declaration field_type named field_name to this event class.

field_type must be one of:

ValueError is raised on error.

fields

Generates the (field name, FieldDeclaration) pairs of this event class.

TypeError is raised on error.

get_field_by_name(name)

Returns the FieldDeclaration object named name in this event class.

TypeError is raised on error.

id

Event class’ numeric ID.

Set this attribute to assign a numeric ID to this event class. This ID must be unique amongst all the event class IDs of a given stream class.

TypeError is raised on error.

name

Event class’ name.

stream_class

StreamClass object containing this event class, or None if not set.

3.6. Event

class babeltrace.writer.Event(event_class)

Events are specific instances of event classes (EventClass), which means they may contain actual, concrete field values.

__init__(event_class)

Creates an event linked with the EventClass event_class.

ValueError is raised on error.

clock()

Clock object used by this object, or None if the event class is not registered to a stream class.

event_class

EventClass object to which this event is linked.

payload(field_name)

Returns the Field object named field_name in this event.

The returned field object is created using the event class’ field declaration named field_name.

The return type is one of:

TypeError is raised on error.

set_payload(field_name, value_field)

Set the event’s field named field_name to the manually created Field object value_field.

value_field’s type must be one of:

ValueError is raised on error.

3.7. FieldDeclaration

class babeltrace.writer.FieldDeclaration

Base class of all field declarations. This class is not meant to be instantiated by the user; use one of the concrete field declaration subclasses instead.

class IntegerBase
alignment

Field alignment in bits (integer).

Set this attribute to change this field’s alignment.

ValueError is raised on error.

byte_order

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

Set this attribute to change this field’s byte order.

ValueError is raised on error.

3.8. IntegerBase

class babeltrace.writer.IntegerBase

Display base of an integer.

BIN = 2

Binary

DEC = 10

Decimal

HEX = 16

Hexadecimal

OCT = 8

Octal

UNKNOWN = -1

Unknown

3.9. IntegerFieldDeclaration

class babeltrace.writer.IntegerFieldDeclaration(size)

Bases: babeltrace.writer.FieldDeclaration

Integer field declaration.

__init__(size)

Creates an integer field declaration of size size bits.

ValueError is raised on error.

base

Integer display base (one of IntegerBase constants).

Set this attribute to change this integer’s display base.

ValueError is raised on error.

encoding

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

Set this attribute to change this integer’s encoding.

ValueError is raised on error.

signed

True if this integer is signed.

Set this attribute to change this integer’s signedness (boolean).

ValueError is raised on error.

size

Integer size in bits (integer).

Set this attribute to change this integer’s size.

ValueError is raised on error.

3.10. FloatingPointFieldDeclaration

class babeltrace.writer.FloatingPointFieldDeclaration

Bases: babeltrace.writer.FieldDeclaration

Floating point number field declaration.

A CTF floating point number is a made of three sections: the sign bit, the exponent bits, and the mantissa bits. The most significant bit of the resulting binary word is the sign bit, and is included in the number of mantissa bits.

For example, the IEEE 754 single precision floating point number is represented on a 32-bit word using an 8-bit exponent (e) and a 24-bit mantissa (m), the latter count including the sign bit (s):

s eeeeeeee mmmmmmmmmmmmmmmmmmmmmmm

The IEEE 754 double precision floating point number uses an 11-bit exponent and a 53-bit mantissa.

__init__()

Creates a floating point number field declaration.

ValueError is raised on error.

DBL_EXP_DIG = 11

IEEE 754 double precision floating point number exponent size

DBL_MANT_DIG = 53

IEEE 754 double precision floating point number mantissa size

FLT_EXP_DIG = 8

IEEE 754 single precision floating point number exponent size

FLT_MANT_DIG = 24

IEEE 754 single precision floating point number mantissa size

exponent_digits

Floating point number exponent section size in bits (integer).

Set this attribute to change the floating point number’s exponent section’s size. You may use FLT_EXP_DIG or DBL_EXP_DIG for IEEE 754 floating point numbers.

ValueError is raised on error.

mantissa_digits

Floating point number mantissa section size in bits (integer).

Set this attribute to change the floating point number’s mantissa section’s size. You may use FLT_MANT_DIG or DBL_MANT_DIG for IEEE 754 floating point numbers.

ValueError is raised on error.

3.11. EnumerationMapping

class babeltrace.writer.EnumerationMapping(name, start, end)

Mapping from an enumeration label to a range of integers.

__init__(name, start, end)

Creates an enumeration mapping, where label name is mapped to the [start, end] range of integers (end is included).

Set start and end to the same value to create an enumeration mapping to a single value.

3.12. EnumerationFieldDeclaration

class babeltrace.writer.EnumerationFieldDeclaration(integer_type)

Bases: babeltrace.writer.FieldDeclaration

Enumeration field declaration. A CTF enumeration maps labels to ranges of integers.

__init__(integer_type)

Creates an enumeration field declaration, with integer_type being the underlying IntegerFieldDeclaration for storing the integer.

ValueError is raised on error.

add_mapping(name, range_start, range_end)

Adds a mapping to the enumeration field declaration, from the label named name to range [range_start, range_end], where range_start and range_end are integers included in the range.

ValueError is raised on error.

container

Underlying container (IntegerFieldDeclaration).

TypeError is raised on error.

get_mapping_by_name(name)

Returns the EnumerationMapping object for the label named name.

TypeError is raised on error.

get_mapping_by_value(value)

Returns the EnumerationMapping object for the value value (integer).

TypeError is raised on error.

mappings

Generates the mappings of this enumeration field declaration (EnumerationMapping objects).

TypeError is raised on error.

3.13. StringFieldDeclaration

class babeltrace.writer.StringFieldDeclaration

Bases: babeltrace.writer.FieldDeclaration

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

__init__()

Creates a string field declaration.

ValueError is raised on error.

encoding

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

Set this attribute to change this string’s encoding.

ValueError is raised on error.

3.14. ArrayFieldDeclaration

class babeltrace.writer.ArrayFieldDeclaration(element_type, length)

Bases: babeltrace.writer.FieldDeclaration

Static array field declaration.

__init__(element_type, length)

Creates a static array field declaration of length elements of type element_type (FieldDeclaration).

ValueError is raised on error.

element_type

Type of the elements of this this static array (subclass of FieldDeclaration).

TypeError is raised on error.

length

Length of this static array (integer).

TypeError is raised on error.

3.15. SequenceFieldDeclaration

class babeltrace.writer.SequenceFieldDeclaration(element_type, length_field_name)

Bases: babeltrace.writer.FieldDeclaration

Sequence (dynamic array) field declaration.

__init__(element_type, length_field_name)

Creates a sequence field declaration of elements of type element_type (FieldDeclaration). The length of a sequence field based on this sequence field declaration is obtained by retrieving the dynamic integer value of the field named length_field_name.

ValueError is raised on error.

element_type

Type of the elements of this sequence (subclass of FieldDeclaration).

TypeError is raised on error.

length_field_name

Name of the integer field defining the dynamic length of sequence fields based on this sequence field declaration.

TypeError is raised on error.

3.16. StructureFieldDeclaration

class babeltrace.writer.StructureFieldDeclaration

Bases: babeltrace.writer.FieldDeclaration

Structure field declaration, i.e. an ordered mapping from field names to field declarations.

__init__()

Creates an empty structure field declaration.

ValueError is raised on error.

add_field(field_type, field_name)

Appends one FieldDeclaration field_type named field_name to the structure’s ordered map.

ValueError is raised on error.

fields

Generates the (field name, FieldDeclaration) pairs of this structure.

TypeError is raised on error.

get_field_by_name(name)

Returns the FieldDeclaration mapped to the field name name in this structure.

TypeError is raised on error.

3.17. VariantFieldDeclaration

class babeltrace.writer.VariantFieldDeclaration(enum_tag, tag_name)

Bases: babeltrace.writer.FieldDeclaration

Variant field declaration.

A CTF variant is a dynamic selection between different fields. The value of a tag (a CTF enumeration) determines what is the current selected field. All the possible fields must be added to its field declaration before using an actual variant field.

__init__(enum_tag, tag_name)

Creates an empty variant field declaration with tag field declaration enum_tag (instance of EnumerationFieldDeclaration) named tag_name (string).

ValueError is raised on error.

add_field(field_type, field_name)

Registers the FieldDeclaration object field_type as the variant’s selected type when the variant’s tag’s current label is field_name.

ValueError is raised on error.

fields

Generates the (field name, FieldDeclaration) pairs of this variant field declaration.

TypeError is raised on error.

get_field_by_name(name)

Returns the FieldDeclaration selected when the variant’s tag’s current label is name.

TypeError is raised on error.

get_field_from_tag(tag)

Returns the FieldDeclaration selected by the current label of the EnumerationField tag.

TypeError is raised on error.

tag_name

Variant field declaration tag name.

TypeError is raised on error.

tag_type

Variant field declaration tag field declaration (EnumerationFieldDeclaration object).

TypeError is raised on error.

3.18. Field

class babeltrace.writer.Field(field_type)

Base class of all fields. This class is not meant to be instantiated by the user, and neither are its subclasses. Use Event.payload() to access specific, concrete fields of an event.

declaration

Field declaration (subclass of FieldDeclaration).

TypeError is raised on error.

3.19. IntegerField

class babeltrace.writer.IntegerField(field_type)

Bases: babeltrace.writer.Field

Integer field, based on an IntegerFieldDeclaration object.

value

Integer value (int).

Set this attribute to change the integer field’s value.

ValueError or TypeError are raised on error.

3.20. FloatingPointField

class babeltrace.writer.FloatingPointField(field_type)

Bases: babeltrace.writer.Field

Floating point number field, based on a FloatingPointFieldDeclaration object.

value

Floating point number value (float).

Set this attribute to change the floating point number field’s value.

ValueError or TypeError are raised on error.

3.21. EnumerationField

class babeltrace.writer.EnumerationField(field_type)

Bases: babeltrace.writer.Field

Enumeration field, based on an EnumerationFieldDeclaration object.

container

Underlying container (IntegerField).

TypeError is raised on error.

value

Current label of this enumeration field (str).

Set this attribute to an integer (int) to change the enumeration field’s value.

ValueError is raised on error.

3.22. StringField

class babeltrace.writer.StringField(field_type)

Bases: babeltrace.writer.Field

String (NULL-terminated array of bytes) field.

value

String value (str).

Set this attribute to change the string’s value.

ValueError or TypeError are raised on error.

3.23. ArrayField

class babeltrace.writer.ArrayField(field_type)

Bases: babeltrace.writer.Field

Static array field, based on an ArrayFieldDeclaration object.

field(index)

Returns the Field at index index in this static array.

IndexError is raised on error.

3.24. SequenceField

class babeltrace.writer.SequenceField(field_type)

Bases: babeltrace.writer.Field

Sequence (dynamic array) field, based on a SequenceFieldDeclaration object.

field(index)

Returns the Field at index index in this sequence.

ValueError is raised on error.

length

Sequence length (IntegerField).

Set this attribute to change the sequence length’s integer field (integer must be unsigned).

ValueError or TypeError are raised on error.

3.25. StructureField

class babeltrace.writer.StructureField(field_type)

Bases: babeltrace.writer.Field

Structure field, based on a StructureFieldDeclaration object.

field(field_name)

Returns the structure Field named field_name.

ValueError is raised on error.

3.26. VariantField

class babeltrace.writer.VariantField(field_type)

Bases: babeltrace.writer.Field

Variant field, based on a VariantFieldDeclaration object.

field(tag)

Returns the Field selected by the current label of tag (EnumerationField).

ValueError is raised on error.