Using the generated C code

This section assumes you ran barectf with no options:

barectf config.yaml

The command generates C structures and functions to initialize barectf contexts, open packets, and close packets. It also generates as many tracing functions as there are events defined in the YAML configuration file.

An application should never have to initialize barectf contexts, open packets, or close packets; this is the purpose of a specific barectf platform, which wraps those calls in its own initialization and finalization functions.

The barectf project provides a few platforms in the platforms directory. Each one contains a README.md file explaining how to use the platform. If you're planning to write your own platform, read the next subsection. Otherwise, skip it.

Calling the generated tracing functions

Calling the generated tracing functions is what the traced application actually does.

For a given prefix named barectf, a given stream named stream, and a given event named event, the generated tracing function name is barectf_stream_trace_event().

The first parameter of a tracing function is always the stream-specific barectf context. Then, in this order:

• One parameter for each custom event header field (prefixed with eh_)
• One parameter for each custom stream event context field (prefixed with ecc_)
• One parameter for each custom event context field (prefixed with sc_)
• One parameter for each custom event payload field (prefixed with p_)

A tracing function returns nothing: it either succeeds (the event is serialized in the current packet) or fails when there's no space left (the context's discarded events count is incremented).

Example:

Given the following event object, named my_event, placed in a stream named default with no custom event header/stream event context fields:

context-type:
  class: struct
  fields:
    msg_id:
      class: int
      size: 16
payload-type:
  class: struct
  fields:
    src:
      class: string
    dst:
      class: string
    a_id:
      class: int
      size: 3
    b_id:
      class: int
      size: 7
      signed: true
    c_id:
      class: int
      size: 15
    amt:
      class: float
      align: 32
      size:
        exp: 8
        mant: 24

barectf will generate the following tracing function prototype:

/* trace (stream "default", event "my_event") */
void barectf_default_trace_my_event(
    struct barectf_default_ctx *ctx,
    uint16_t sc_msg_id,
    const char *p_src,
    const char *p_dst,
    uint8_t p_a_id,
    int8_t p_b_id,
    uint16_t p_c_id,
    float p_amt
);