Use the generated C tracing functions

This page assumes that the configured identifier prefix is the default barectf.

The public barectf.h header which barectf generates contains two groups of function prototypes:

Tracing functions

barectf generates one tracing function per configured event record type.

A tracing function is named barectf_trace_DSTNAME_ERTNAME(), where DSTNAME is the data stream type name and ERTNAME the event record type name.

If your configuration has a default data stream type named DEFDSTNAME, then barectf also generates C preprocessor definitions named barectf_trace_ERTNAME which are set to barectf_trace_DEFDSTNAME_ERTNAME.

Those are the functions which your application can call to write CTF event records to data streams.

Tracing control functions

barectf generates the barectf_is_tracing_enabled() and barectf_enable_tracing() functions to control the tracing activity for a given barectf context.

Platform API functions

barectf generates one packet opening and one packet closing function per configured data stream type.

It also generates a barectf context initialization function and a few context property getters and setters.

The suggested barectf approach is for a platform to handle the barectf context initialization, packet opening and packet closing operations.

This hides the details of how packets are written to the back end from the application so that it only calls tracing and tracing control functions.

Obtain a barectf context pointer

Tracing and tracing control functions accept a barectf context pointer as their first parameter.

For example:

void barectf_my_stream_trace_my_event(struct barectf_my_stream_ctx *sctx,
                                      uint8_t p_user_id, const char *p_msg);

int barectf_is_tracing_enabled(const void *vctx);

void barectf_enable_tracing(void *vctx, int enable);

A barectf context represents a CTF data stream.

The suggested barectf approach is for a platform's API to offer a function to obtain a pointer to an initialized barectf context.

For example, the Linux FS demonstration platform offers the barectf_platform_linux_fs_get_barectf_ctx() function to obtain a barectf context pointer from a platform context.

Tracing function parameters

As explained in Obtain a barectf context pointer, a tracing function’s first parameter is always a barectf context pointer.

The other parameters depend on the configuration.

For a given data stream type and event record type, the generated tracing function parameters are, in this order:

For each member NAME of the event record common context structure field type, a parameter named cc_NAME.
For each member NAME of the event record specific context structure field type, a parameter named sc_NAME.
For each member NAME of the event record payload structure field type, a parameter named p_NAME.

See Generated C types to determine the exact C type of each parameter.

Note that a member with a dynamic array field type actually makes barectf generate two adjacent parameters:

One for the dynamic array’s length.

Example: uint32_t p___my_array_len
One for the dynamic array’s data.

Example: const uint8_t *p_my_array

Consider this data stream type object named my_stream:

event-record-common-context-field-type:
  class: structure
  members:
    - pid: uint32
    - t_level: double
event-record-types:
  my_event:
    specific-context-field-type:
      class: structure
      members:
        - count: uint16
    payload-field-type:
      class: structure
      members:
        - msg: string
        - src_ip_addr:
            field-type:
              class: static-array
              length: 4
              element-field-type: uint8

The generated tracing prototype for the my_event event record type is:

void barectf_my_stream_trace_my_event(struct barectf_my_stream_ctx *sctx,
                                      uint32_t cc_pid, double cc_t_level,
                                      uint16_t sc_count, const char *p_msg,
                                      const uint8_t *p_src_ip_addr);

Control tracing

You can control the tracing activity for a given barectf context with the following functions:

```
int barectf_is_tracing_enabled(const void *vctx);
```
Returns whether or not tracing is currenty enabled for the barectf context vctx.
```
void barectf_enable_tracing(void *vctx, int enable);
```
Enables (if enable is 1) or disables (if enable is 0) tracing for the barectf context vctx.

When tracing is disabled for a given barectf context, the tracing functions have no effect for this context.

Concurrent access safety

The C source code which barectf generates doesn’t guarantee any concurrent access safety (thread safety, reentrancy).

Because barectf generates general ANSI C code with no dependencies, it can’t know how to synchronize accesses to barectf context structures. As of barectf 3.1, you need to protect tracing function calls for a given barectf context with your own synchronization primitives.

Note, however, that CTF is designed for fast multicore/multithread tracing: dedicate one barectf context (one data stream) per core/thread to avoid tracing function locking.