Stream object

A CTF stream.

Stream objects are used in the streams property of the metadata object.

Properties

Property	Type	Description	Required?	Default value
$default	Boolean	True if this stream is the default stream	Optional	false
packet-context-type	Structure type object or string (alias name)	Type of packet context	Required	N/A
event-header-type	Structure type object or string (alias name)	Type of event header	Optional	No event header
event-context-type	Structure type object or string (alias name)	Type of stream event context	Optional	No stream event context
events	Associative array of event names (string) to Event objects	Stream events	Required	N/A
$include (Including external YAML files)	String or array of strings	Include base properties from external YAML file(s)	Optional	[]

All the properties which have a default value can also be set to null to force this default value. This is especially useful when including external YAML files.

The $default property, if true, must not be set to false in other streams. Note that you can also set the default stream by name with the $default-stream property of the metadata object.

Each field of the packet context structure type (packet-context-type property) corresponds to one parameter of the generated packet opening function (prefixed with pc_), except for the following special fields, which are automatically written if present:

• timestamp_begin and timestamp_end (unsigned integer type objects, with a clock value property mapping): resp. open and close timestamps
• packet_size (unsigned integer type object, mandatory): packet size
• content_size (unsigned integer type object, mandatory): content size
• events_discarded (unsigned integer type object): number of discarded events so far

The timestamp_end field must exist if the timestamp_begin field exists, and vice versa.

The event header structure type (event-header-type property) can only contain the following special fields, which are automatically written by the generated tracer if present:

• id (unsigned integer type object): event ID
• timestamp (unsigned integer type object, with a clock value property mapping): event timestamp

The id field must exist if there's more than one defined event in the stream.

Each field of the stream event context structure type (event-context-type property) corresponds to one parameter of the generated tracing function (prefixed with ecc_) (for a given event).

Each field name of the packet-context-type, event-header-type, and event-context-type properties must be a valid C identifier.

The events property must contain at least one entry.

Example

$default: true
packet-context-type:
  class: struct
  fields:
    timestamp_begin: clock-int
    timestamp_end: clock-int
    packet_size: uint32
    content_size: uint32
    events_discarded: uint16
    my_custom_field: int12
event-header-type:
  class: struct
  fields:
    id: uint16
    timestamp: clock-int
event-context-type:
  class: struct
  fields:
    obj_id: uint8
events:
  msg_in:
    payload-type: msg-type