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.

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:

  1. The value of each --include-dir option, in order.

  2. The current working directory.

  3. 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 <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.

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.