Write a barectf YAML configuration file

A barectf configuration controls how barectf generates a tracer, for example:

  • What are the event record types for which to generate tracing functions?

    In other words, what are the tracing function names and what are their parameter types and names?

  • Does a data stream have a clock source? If so, what’s the clock source function’s return C type?

  • What’s the identifier prefix for the C source code which barectf generates?

    By default, a tracing function name could be barectf_trace_my_stream_my_event(), but it can also be my_company_trace_my_stream_my_event().

barectf supports two methods to write a configuration:

  1. Create and assemble configuration objects with the barectf Python API (barectf package).

  2. Write a configuration in YAML.

This section is about method 2.

Read YAML primer to learn more about the YAML language.

A barectf YAML configuration document is a configuration object.

In a barectf YAML configuration, a null value always means to use the default value.

This is useful when taking into account the partial YAML file inclusion or field type object inheritance features: the overriding object can reset properties to their default values.

Processing stages

barectf goes through the following stages when it processes a YAML configuration:

  1. Include, recursively, partial YAML files.

  2. Expand field type aliases.

    Replace every field type alias with its full field type object, recursively.

  3. Apply field type object inheritance.

  4. Expand log level aliases.

    Replace every log level alias with its numeric value.

  5. Normalize property values.

    If more than one value mean the same thing (for example, be and big-endian), prefer one version.

A configuration object, after step 5, is known as an effective configuration object. The barectf show-effective-configuration CLI command shows the effective version of a YAML configuration file.

TSDL identifier

Many barectf YAML objects require that a given string key or value be a valid TSDL (Trace Stream Description Language) identifier.

As per CTF 1.8.3, a valid TSDL identifier is any valid C identifier which is not one of:

  • align

  • callsite

  • const

  • char

  • clock

  • double

  • enum

  • env

  • event

  • floating_point

  • float

  • integer

  • int

  • long

  • short

  • signed

  • stream

  • string

  • struct

  • trace

  • typealias

  • typedef

  • unsigned

  • variant

  • void

  • _Bool

  • _Complex

  • _Imaginary