barectf is a command-line utility which generates C99 code that is able to write native Common Trace Format (CTF) binary streams.

You will find barectf interesting if:

1. You need to trace an application.
2. You need tracing to be efficient, yet flexible: record integers of custom sizes, custom floating point numbers, enumerations supported by a specific integer type, and null-terminated UTF-8/ASCII strings (C strings).
3. You need to be able to convert the recorded binary events to human-readable text, as well as analyze them with Python scripts (Babeltrace does all that, given a CTF input).
4. You cannot use LTTng, an efficient tracing framework for the Linux kernel and Linux/BSD user applications, which also outputs CTF.

The target audience of barectf is developers who need to trace bare metal systems (without an operating system). The code produced by barectf is pure C99 and can be lightweight enough to fit on a tiny microcontroller.

Key features:

• Single input: easy-to-write YAML configuration file
• 1-to-1 mapping from tracing function parameters to event fields
• Custom and bundled platforms hiding the details of opening/closing packets and writing them to a back-end (continuous tracing), getting the clock values, etc.:
  • linux-fs: basic Linux application tracing writing stream files to the file system for demonstration purposes
  • parallella: Adapteva Epiphany/Parallella with host-side consumer
• CTF metadata generated by the command-line tool (automatic trace UUID, stream IDs, and event IDs)
• All basic CTF types are supported: integers, floating point numbers, enumerations, and null-terminated strings (C strings)
• Binary streams produced by the generated C code and metadata file produced by barectf are CTF 1.8-compliant
• Human-readable error reporting

Current limitations:

As of this version:

• All the generated tracing C functions, for a given barectf stream-specific context, need to be called from the same thread, and cannot be called from an interrupt handler, unless a user-provided synchronization mechanism is used.
• CTF compound types (array, sequence, structure, variant) are not supported yet, except at some very specific locations in the metadata.
• The current generated C code is not strictly C99 compliant: statement expressions and the typeof keyword GCC extensions are used in the generated bitfield macros. The generated C code is known to be compiled with no warnings using both GCC and Clang.

barectf is written in Python 3.

Make sure you have Python 3 and pip for Python 3 installed, then install barectf.

Note that you may pass the --user argument to pip install to install the tool in your home directory (instead of installing globally).

Ubuntu 14.04 and 16.04:

It is recommended to use the barectf PPA, which also installs the man page:

sudo apt-add-repository ppa:lttng/barectf
sudo apt-get update
sudo apt-get install barectf

Otherwise, you can always use pip3:

sudo apt-get install python3-pip
sudo pip3 install barectf

Other, recent Ubuntu:

sudo apt-get install python3-pip
sudo pip3 install barectf

Ubuntu 12.04 and lower:

sudo apt-get install python3-setuptools
sudo easy_install3 pip
sudo pip3 install barectf

Debian:

sudo apt-get install python3-pip
sudo pip3 install barectf

Fedora 20 and up:

sudo yum install python3-pip
sudo pip3 install barectf

Arch Linux:

It is recommended to use the AUR package, which also installs the man page. If you have yaourt:

sudo yaourt -Sy barectf

Otherwise, you can always use pip:

sudo pacman -S python-pip
sudo pip install barectf

OS X:

With Homebrew:

brew install python3
pip3 install barectf

Since the philosophy of setuptools packages is to include everything within the package, the barectf man page is not installed on the system when installing barectf with pip or with setup.py. This would be the job of distribution packages.

You can install it manually:

wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1

Replace VERSION with the desired version, for example:

wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1

See the CTF in a nutshell section of CTF's website to understand the basics of this trace format.

The most important thing to understand about CTF, for barectf use cases, is the layout of a binary stream packet:

• Packet header (defined at the trace level)
• Packet context (defined at the stream level)
• Sequence of events (defined at the stream level):
  • Event header (defined at the stream level)
  • Stream event context (defined at the stream level)
  • Event context (defined at the event level)
  • Event payload (defined at the event level)

The following diagram, stolen without remorse from CTF's website, shows said packet layout:

Any of those six dynamic scopes, if defined at all, has an associated CTF type. barectf requires them to be structure types.

See the project's wiki which contains all the information needed to use barectf.

Bash is required for testing barectf.

The barectf tests execute the barectf command available in your $PATH. The best way to test a specific version of barectf is to create a Python 3 virtual environment, install the appropriate version, and then run the tests.

In the barectf source tree root, do:

virtualenv --python=python3 virt
. ./virt/bin/activate
rehash # if using zsh
./setup.py install
(cd tests && ./test.bash)

You can specify Bats options to ./test.bash, like --tap to get a TAP output.

You can exit the virtual environment by running deactivate.

Since the barectf community is small, it's sharing the communication channels of the LTTng project, as EfficiOS is the main sponsor of both projects. It goes like this: