docs/modules/yaml/pages/include.adoc

   1 = Include partial YAML files
   2
   3 You can include a partial YAML file from specific objects within the
   4 xref:cfg-obj.adoc[configuration object]:
   5
   6 * xref:trace-obj.adoc[Trace object]
   7 * xref:trace-type-obj.adoc[Trace type object]
   8 * xref:clk-type-obj.adoc[Clock type object]
   9 * xref:dst-obj.adoc[Data stream type object]
  10 * xref:ert-obj.adoc[Event record type object]
  11
  12 Each of the objects above can have an `$include` property which is a
  13 sequence of names of files to include.
  14
  15 By choosing where to include partial YAML files strategically, you can
  16 split a configuration object into multiple reusable parts for different
  17 systems or projects.
  18
  19 == Inclusion file search
  20
  21 barectf tries to find each file of an `$include` property sequence in
  22 specific directories.
  23
  24 When using the `barectf` CLI tool's
  25 xref:cli:usage.adoc#generate-command[`generate`] or
  26 xref:cli:usage.adoc#show-effective-configuration-command[`show-effective-configuration`]
  27 commands, the inclusion directory search order is:
  28
  29 . The value of each
  30   xref:cli:usage.adoc#generate-include-dir-option[`+--include-dir+`]
  31   option, in order.
  32
  33 . The current working directory.
  34
  35 . The directory containing the <<std,standard inclusion files>> (like
  36   `stdint.yaml` and `stdmisc.yaml`).
  37
  38 By default, if `barectf` can't find an inclusion file, the command
  39 prints an error and xref:cli:usage.adoc#exit-status[exits] with a
  40 non-zero status. Force `barectf` to continue silently instead with its
  41 xref:cli:usage.adoc#generate-ignore-include-not-found-option[`+--ignore-include-not-found+`]
  42 option.
  43
  44 == Inclusion rules
  45
  46 With the `$include` property, an object _includes_ the properties of
  47 one or more YAML documents.
  48
  49 barectf processes the items of the `$include` property sequence
  50 in order.
  51
  52 When an object __**A**__ includes a YAML document __**B**__, the
  53 _effective_ object is __**A**__ "`patching`" __**B**__.
  54
  55 include::partial$patching-rules-table.adoc[]
  56
  57 === Examples
  58
  59 .Override scalar property (xref:ert-obj.adoc[event record type object]).
  60 ====
  61 .`base.yaml`
  62 [source,yaml]
  63 ----
  64 log-level: WARN
  65 payload-field-type:
  66   class: structure
  67   members:
  68     - msg: string
  69     - msg_id: uint16
  70 ----
  71
  72 .Overlay event record type object
  73 [source,yaml]
  74 ----
  75 $include: [base.yaml]
  76 log-level: ERROR
  77 ----
  78
  79 .Effective event record type object
  80 [source,yaml]
  81 ----
  82 log-level: ERROR
  83 payload-field-type:
  84   class: structure
  85   members:
  86     - msg: string
  87     - msg_id: uint16
  88 ----
  89 ====
  90
  91 .Add and override scalar properties (xref:clk-type-obj.adoc[clock type object]).
  92 ====
  93 .`base.yaml`
  94 [source,yaml]
  95 ----
  96 frequency: 1000000
  97 offset:
  98   seconds: 1992839
  99 ----
 100
 101 .Overlay clock type object
 102 [source,yaml]
 103 ----
 104 $include: [base.yaml]
 105 frequency: 8000000
 106 origin-is-unix-epoch: false
 107 ----
 108
 109 .Effective clock type object
 110 [source,yaml]
 111 ----
 112 frequency: 8000000
 113 offset:
 114   seconds: 1992839
 115 origin-is-unix-epoch: false
 116 ----
 117 ====
 118
 119 .Append to sequence property (xref:trace-type-obj.adoc[trace type object]).
 120 ====
 121 .`base.yaml`
 122 [source,yaml]
 123 ----
 124 $field-type-aliases:
 125   my-enum:
 126     class: signed-enumeration
 127     mappings:
 128       COMPOSE:
 129         - 56
 130         - [100, 299]
 131       DIRTY: [0]
 132 ----
 133
 134 .Overlay trace type object
 135 [source,yaml]
 136 ----
 137 $include: [base.yaml]
 138 $field-type-aliases:
 139   my-enum:
 140     size: 16
 141     mappings:
 142       COMPOSE:
 143         - -22
 144 # ...
 145 ----
 146
 147 .Effective trace type object
 148 [source,yaml]
 149 ----
 150 $field-type-aliases:
 151   my-enum:
 152     class: signed-enumeration
 153     size: 16
 154     mappings:
 155       COMPOSE:
 156         - 56
 157         - [100, 299]
 158         - -22
 159       DIRTY: [0]
 160 # ...
 161 ----
 162 ====
 163
 164 .Add to nested mapping property (event record type object).
 165 ====
 166 .`base.yaml`
 167 [source,yaml]
 168 ----
 169 specific-context-field-type:
 170   class: structure
 171   members:
 172     - msg: string
 173     - user_id: uint16
 174 ----
 175
 176 .Overlay event record type object
 177 [source,yaml]
 178 ----
 179 $include: [base.yaml]
 180 specific-context-field-type:
 181   class: structure
 182   members:
 183     - src_ip_addr:
 184         field-type:
 185           class: static-array
 186           length: 4
 187           element-field-type: uint8
 188     - user_id: int8
 189 ----
 190
 191 .Effective event record type object
 192 [source,yaml]
 193 ----
 194 specific-context-field-type:
 195   class: structure
 196   members:
 197     - msg: string
 198     - user_id: int8
 199     - src_ip_addr:
 200         field-type:
 201           class: static-array
 202           length: 4
 203           element-field-type: uint8
 204 ----
 205 ====
 206
 207 [[std]]
 208 == Standard partial YAML files
 209
 210 The barectf project ships with a few "`standard`" partial YAML files
 211 to be included from a xref:trace-type-obj.adoc[trace type object]:
 212
 213 https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/stdint.yaml[`stdint.yaml`]::
 214     Standard xref:int-ft-obj.adoc[integer]
 215     xref:trace-type-obj.adoc#ft-aliases-prop[field type aliases], like
 216     `uint8`, `byte-packed-sint16`, and `bit-packed-uint64`.
 217
 218 https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/stdreal.yaml[`stdreal.yaml`]::
 219     Standard xref:real-ft-obj.adoc[real] field type aliases, like
 220     `float` and `double`.
 221
 222 https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/stdmisc.yaml[`stdmisc.yaml`]::
 223     The `string` and `str` xref:str-ft-obj.adoc[string] field type
 224     aliases.
 225
 226 https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/lttng-ust-log-levels.yaml[`lttng-ust-log-levels.yaml`]::
 227     xref:trace-type-obj.adoc#ll-aliases-prop[Log level aliases] which
 228     correspond to the https://lttng.org/[LTTng-UST] log levels.