Include partial YAML files

You can include a partial YAML file from specific objects within the configuration object:

Each of the objects above can have an $include property which is a sequence of names of files to include.

By choosing where to include partial YAML files strategically, you can split a configuration object into multiple reusable parts for different systems or projects.

Inclusion file search

barectf tries to find each file of an $include property sequence in specific directories.

When using the barectf CLI tool’s generate or show-effective-configuration commands, the inclusion directory search order is:

The value of each --include-dir option, in order.
The current working directory.
The directory containing the standard inclusion files (like stdint.yaml and stdmisc.yaml).

By default, if barectf can’t find an inclusion file, the command prints an error and exits with a non-zero status. Force barectf to continue silently instead with its --ignore-include-not-found option.

Inclusion rules

With the $include property, an object includes the properties of one or more YAML documents.

barectf processes the items of the $include property sequence in order.

When an object A includes a YAML document B, the effective object is A “patching” B.

For a given property of A, the patching rules are:

A's property type A's property exists in B A's property doesn’t exist in B

A's property type	<em>A</em>'s property exists in <em>B</em>	<em>A</em>'s property doesn’t exist in <em>B</em>
Null, boolean, integer, and string	Replace B's property with A's property.	Keep A's property.
Sequence	B's property is also a sequence Append the items of A's property to B's property. A structure field type object’s `members` property is an exception: A's property is considered to be an ordered mapping, therefore apply the mapping patching rules. B's property is not a sequence Replace B's property with A's property.	Keep A's property.
Mapping	B's property is also a mapping Patch A's property over B's property according to those rules. B's property is not a mapping Replace B's property with A's property.	Keep A's property.

Null, boolean, integer, and string

Replace B's property with A's property.

Keep A's property.

Sequence

B's property is also a sequence: Append the items of A's property to B's property.

A structure field type object’s members property is an exception: A's property is considered to be an ordered mapping, therefore apply the mapping patching rules.
B's property is not a sequence: Replace B's property with A's property.

Keep A's property.

Mapping

B's property is also a mapping: Patch A's property over B's property according to those rules.
B's property is not a mapping: Replace B's property with A's property.

Keep A's property.

When A's property replaces B's property and the value of A's property is null, this effectively “resets” the property to its default value.

Examples

Example 1. Override scalar property (event record type object).

base.yaml

log-level: WARN
payload-field-type:
  class: structure
  members:
    - msg: string
    - msg_id: uint16

Overlay event record type object

$include: [base.yaml]
log-level: ERROR

Effective event record type object

log-level: ERROR
payload-field-type:
  class: structure
  members:
    - msg: string
    - msg_id: uint16

Example 2. Add and override scalar properties (clock type object).

base.yaml

frequency: 1000000
offset:
  seconds: 1992839

Overlay clock type object

$include: [base.yaml]
frequency: 8000000
origin-is-unix-epoch: false

Effective clock type object

frequency: 8000000
offset:
  seconds: 1992839
origin-is-unix-epoch: false

Example 3. Append to sequence property (trace type object).

base.yaml

$field-type-aliases:
  my-enum:
    class: signed-enumeration
    mappings:
      COMPOSE:
        - 56
        - [100, 299]
      DIRTY: [0]

Overlay trace type object

$include: [base.yaml]
$field-type-aliases:
  my-enum:
    size: 16
    mappings:
      COMPOSE:
        - -22
# ...

Effective trace type object

$field-type-aliases:
  my-enum:
    class: signed-enumeration
    size: 16
    mappings:
      COMPOSE:
        - 56
        - [100, 299]
        - -22
      DIRTY: [0]
# ...

Example 4. Add to nested mapping property (event record type object).

base.yaml

specific-context-field-type:
  class: structure
  members:
    - msg: string
    - user_id: uint16

Overlay event record type object

$include: [base.yaml]
specific-context-field-type:
  class: structure
  members:
    - src_ip_addr:
        field-type:
          class: static-array
          length: 4
          element-field-type: uint8
    - user_id: int8

Effective event record type object

specific-context-field-type:
  class: structure
  members:
    - msg: string
    - user_id: int8
    - src_ip_addr:
        field-type:
          class: static-array
          length: 4
          element-field-type: uint8

Standard partial YAML files

The barectf project ships with a few “standard” partial YAML files to be included from a trace type object:

stdint.yaml: Standard integer field type aliases, like uint8, byte-packed-sint16, and bit-packed-uint64.
stdreal.yaml: Standard real field type aliases, like float and double.
stdmisc.yaml: The string and str string field type aliases.
lttng-ust-log-levels.yaml: Log level aliases which correspond to the LTTng-UST log levels.