Getting started

This introductory guide makes you create a very simple barectf YAML configuration, generate a tracer out of it, and then use it.

You need Linux for this user guide.

The steps are:

Make sure that barectf is installed before you follow this guide.

Write the YAML configuration file

  1. Create an empty directory and cd into it, for example:

    $ cd $(mktemp --directory)
  2. Write the following YAML configuration file:

    # Needed YAML tag for the configuration object
    --- !<,2020/3/config>
    # Configuration's trace
      # Type of the trace
        # Add standard field type aliases
          - stdint.yaml
          - stdmisc.yaml
        # Native byte order is little-endian
        native-byte-order: little-endian
        # One clock type
          # The Linux FS platform requires a clock type named `default`
          # which has a 1-GHz frequency and the `uint64_t` C type.
            frequency: 1000000000
            $c-type: uint64_t
        # One data stream type
          # Stream type named `default`
            # Default data stream type
            $is-default: true
            # Default clock type: `default`
            $default-clock-type-name: default
            # Two event record types
              # Event record type named `one_integer`
                  class: structure
                    # One payload member: a 32-bit signed integer field type
                    # (`int32_t` C type)
                    - the_integer: int32
              # Event record type named `one_string`
                  class: structure
                    # One payload member: a string field type
                    # (`const char *` C type)
                    - the_string: string

    barectf will generate two tracing functions named barectf_trace_one_integer() and barectf_trace_one_string() from this configuration.

Generate the files with the barectf CLI tool

  1. Create a directory which will contain the CTF trace:

    $ mkdir trace

    A CTF trace always contains a file named metadata and one or more data stream files. barectf always generates the metadata file while the user application writes the data stream files through the generated tracer.

  2. Generate the CTF metadata stream and C source files with the barectf CLI tool:

    $ barectf generate --metadata-dir=trace config.yaml

    barectf generate creates:

    File name Description


    The CTF metadata stream file.

    It’s in the trace directory because we used the --metadata-dir option.


    The generated tracer’s public C header file.


    Internal macros for the generated tracer (included by barectf.c).


    The generated tracer’s C source code.

Write the application source file

Write a simple application which uses the generated tracer:

/* Include the Linux FS platform header */
#include "barectf-platform-linux-fs.h"

/* Include the barectf public header */
#include "barectf.h"

int main(const int argc, const char * const argv[])
    /* Platform context */
    struct barectf_platform_linux_fs_ctx *platform_ctx;

    /* barectf context */
    struct barectf_default_ctx *ctx;

    int i;

     * Obtain a platform context.
     * The platform is configured to write 512-byte packets to a data
     * stream file within the `trace` directory.
    platform_ctx = barectf_platform_linux_fs_init(512, "trace/stream",
                                                  0, 0, 0);

    /* Obtain the barectf context from the platform context */
    ctx = barectf_platform_linux_fs_get_barectf_ctx(platform_ctx);

     * Write a `one_integer` event record which contains the number of
     * command arguments.
    barectf_trace_one_integer(ctx, argc);

    /* For each command argument */
    for (i = 0; i < argc; ++i) {
         * Write a `one_integer` event record which contains the
         * argument's index.
        barectf_trace_one_integer(ctx, i);

         * Write a `one_string` event record which contains the
         * argument.
        barectf_trace_one_string(ctx, argv[i]);

    /* Finalize (free) the platform context */

    return 0;

This application calls the barectf_trace_one_integer() and barectf_trace_one_string() functions which correspond to the one_integer and one_string event record types in config.yaml.

Download platform source files and build the application

To build the final application, you need the Linux FS platform source files.

The Linux FS platform only exists to demonstrate barectf; a barectf user almost always writes its own platform because of the bare-metal/embedded nature of the target systems.

Execute the application

Run the built application, passing a few command-line arguments:

$ ./app lorem ipsum nulla dolore consequat

This writes the CTF data stream file trace/stream.

The trace directory is now a complete CTF trace.

Read the CTF trace

Use Babeltrace 2 to read the resulting CTF trace:

$ babeltrace2 trace
[15:52:24.202028327] (+?.?????????) one_integer: { the_integer = 6 }
[15:52:24.202029477] (+0.000001150) one_integer: { the_integer = 0 }
[15:52:24.202029988] (+0.000000511) one_string: { the_string = "./app" }
[15:52:24.202033362] (+0.000003374) one_integer: { the_integer = 1 }
[15:52:24.202033716] (+0.000000354) one_string: { the_string = "lorem" }
[15:52:24.202034147] (+0.000000431) one_integer: { the_integer = 2 }
[15:52:24.202034465] (+0.000000318) one_string: { the_string = "ipsum" }
[15:52:24.202034812] (+0.000000347) one_integer: { the_integer = 3 }
[15:52:24.202035147] (+0.000000335) one_string: { the_string = "nulla" }
[15:52:24.202035527] (+0.000000380) one_integer: { the_integer = 4 }
[15:52:24.202035848] (+0.000000321) one_string: { the_string = "dolore" }
[15:52:24.202036175] (+0.000000327) one_integer: { the_integer = 5 }
[15:52:24.202036553] (+0.000000378) one_string: { the_string = "consequat" }

You can also open the trace with Trace Compass:

getting started trace compass
Figure 1. Trace Compass 5.3.0’s event list view