CTF primer

The Common Trace Format (CTF) is a binary trace format which is designed to be very fast to write while offering many field types to represent data.

A barectf configuration can use the following CTF field types:

  • Unsigned/signed integer (1 to 64 bits).

  • Unsigned/signed enumeration (1 to 64 bits).

  • Real (single or double precision).

  • Null-terminated string.

  • Structure (zero or more named members).

  • Static array of any field type except structure and dynamic array.

  • Dynamic array of any field type except structure and dynamic array.

CTF makes it possible to describe the alignment and byte order of integer, enumeration, and real fields.

A system which produces CTF streams is known as a CTF producer.

A system which consumes CTF streams is known as a CTF consumer.

CTF trace structure

A CTF trace is exactly one metadata stream and one or more data streams:

ctf trace

The metadata stream describes the trace’s data streams with TSDL (Trace Stream Description Language). On the file system, its file name must be metadata.

The metadata stream describes things such as:

  • The type of the data stream default clocks.

  • The names of event record types.

  • The types of event record fields.

  • The trace's environment variables.

Data stream

A CTF data stream is a sequence of one or more data packets:

ctf trace all

A data stream type describes data streams.

A packet contains one or more bytes of data.

Although a packet can contain padding itself, from the data stream’s point of view, there’s no padding between packets.

A data stream can have, conceptually:

A default clock

Described by a clock type in the trace’s metadata stream.

Packets and event records can contain snapshots, named timestamps, of their data stream’s clock.

A counter of discarded event records

Indicates the number of event records which the generated tracer needed to discard for different reasons.

For example, the tracer discards an event record when it doesn’t fit the current packet and the back end is full (see Write a barectf platform).

A packet can contain a snapshot of this counter.

On the file system, a data stream file:

  • Can have any name, except metadata and anything which begins with ..

  • Must be in the same directory as the metadata file.

Packet

A CTF packet is a part of a data stream.

A packet contains, in this order:

  1. OptionalA header structure field, which contains:

  2. A context structure field, which contains:

  3. Zero or more event records.

A packet contains one or more bytes of data.

A packet can have padding (garbage data) after its last event record if its total size is different from its content size.

Event record

A CTF event record is the result of a tracer writing a time-stamped record with user data when an event occurs during a user application’s execution.

An event record type describes event records.

An event record contains, in this order:

  1. OptionalA header structure field, which contains:

    • OptionalThe numeric ID of the event record type which, in the metadata stream, describes this event record.

      See the data stream type event record features object’s type-id-field-type property.

    • OptionalA timestamp.

      See the data stream type event record features object’s timestamp-field-type property.

  2. OptionalA common context structure field, which contains user fields.

    See the data stream type object’s event-record-common-context-field-type property.

  3. OptionalA specific context structure field, which contains user fields.

    See the event record type object’s specific-context-field-type property.

  4. OptionalA payload structure field, which contains user fields.

    See the event record type object’s payload-field-type property.