| 1 | ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png) |
| 2 | |
| 3 | [![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf) |
| 4 | [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf.svg)](https://ci.lttng.org/job/barectf) |
| 5 | |
| 6 | **barectf** is a command-line utility which generates C99 |
| 7 | code that is able to write native [Common Trace Format](http://diamon.org/ctf) |
| 8 | (CTF) binary streams. |
| 9 | |
| 10 | You will find barectf interesting if: |
| 11 | |
| 12 | 1. You need to trace an application. |
| 13 | 2. You need tracing to be efficient, yet flexible: |
| 14 | record integers of custom sizes, custom floating point numbers, |
| 15 | enumerations supported by a specific integer type, and |
| 16 | null-terminated UTF-8/ASCII strings (C strings). |
| 17 | 3. You need to be able to convert the recorded binary events to |
| 18 | human-readable text, as well as analyze them with Python scripts |
| 19 | ([Babeltrace](http://diamon.org/babeltrace/) does all that, |
| 20 | given a CTF input). |
| 21 | 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing |
| 22 | framework for the Linux kernel and Linux/BSD user applications, which |
| 23 | also outputs CTF. |
| 24 | |
| 25 | The target audience of barectf is developers who need to trace bare metal |
| 26 | systems (without an operating system). The code produced by barectf |
| 27 | is pure C99 and can be lightweight enough to fit on a tiny microcontroller. |
| 28 | |
| 29 | **Key features**: |
| 30 | |
| 31 | * Single input: easy-to-write [YAML configuration |
| 32 | file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file) |
| 33 | * 1-to-1 mapping from tracing function parameters to event fields |
| 34 | * Custom and bundled |
| 35 | [_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform) |
| 36 | hiding the details of opening/closing packets and writing them to a |
| 37 | back-end (continuous tracing), getting the clock values, etc.: |
| 38 | * _linux-fs_: basic Linux application tracing writing stream files to |
| 39 | the file system for demonstration purposes |
| 40 | * _parallella_: Adapteva Epiphany/[Parallella](http://parallella.org/) |
| 41 | with host-side consumer |
| 42 | * CTF metadata generated by the command-line tool (automatic trace UUID, |
| 43 | stream IDs, and event IDs) |
| 44 | * All basic CTF types are supported: integers, floating point numbers, |
| 45 | enumerations, and null-terminated strings (C strings) |
| 46 | * Binary streams produced by the generated C code and metadata file |
| 47 | produced by barectf are CTF 1.8-compliant |
| 48 | * Human-readable error reporting |
| 49 | |
| 50 | **Current limitations**: |
| 51 | |
| 52 | As of this version: |
| 53 | |
| 54 | * All the generated tracing C functions, for a given barectf |
| 55 | stream-specific context, need to be called from the same thread, and cannot |
| 56 | be called from an interrupt handler, unless a user-provided |
| 57 | synchronization mechanism is used. |
| 58 | * CTF compound types (array, sequence, structure, variant) are not supported |
| 59 | yet, except at some very specific locations in the metadata. |
| 60 | * The current generated C code is not strictly C99 compliant: |
| 61 | [statement expressions](https://gcc.gnu.org/onlinedocs/gcc/Statement-Exprs.html) |
| 62 | and the |
| 63 | [`typeof` keyword](https://gcc.gnu.org/onlinedocs/gcc/Typeof.html) |
| 64 | GCC extensions are used in the generated bitfield macros. The |
| 65 | generated C code is known to be compiled with no warnings using |
| 66 | both GCC and Clang. |
| 67 | |
| 68 | barectf is written in Python 3. |
| 69 | |
| 70 | |
| 71 | ## Installing |
| 72 | |
| 73 | Make sure you have Python 3 and `pip` for Python 3 installed, then |
| 74 | install barectf. |
| 75 | |
| 76 | Note that you may pass the `--user` argument to |
| 77 | `pip install` to install the tool in your home directory (instead of |
| 78 | installing globally). |
| 79 | |
| 80 | **Latest Ubuntu**: |
| 81 | |
| 82 | sudo apt-get install python3-pip |
| 83 | sudo pip3 install barectf |
| 84 | |
| 85 | **Ubuntu 12.04 and lower**: |
| 86 | |
| 87 | sudo apt-get install python3-setuptools |
| 88 | sudo easy_install3 pip |
| 89 | sudo pip3 install barectf |
| 90 | |
| 91 | **Debian**: |
| 92 | |
| 93 | sudo apt-get install python3-pip |
| 94 | sudo pip3 install barectf |
| 95 | |
| 96 | **Fedora 20 and up**: |
| 97 | |
| 98 | sudo yum install python3-pip |
| 99 | sudo pip3 install barectf |
| 100 | |
| 101 | **Arch Linux**: |
| 102 | |
| 103 | sudo pacman -S python-pip |
| 104 | sudo pip install barectf |
| 105 | |
| 106 | **OS X** |
| 107 | |
| 108 | With [Homebrew](http://brew.sh/): |
| 109 | |
| 110 | brew install python3 |
| 111 | pip3 install barectf |
| 112 | |
| 113 | |
| 114 | ## What is CTF? |
| 115 | |
| 116 | See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell) |
| 117 | section of CTF's website to understand the basics of this |
| 118 | trace format. |
| 119 | |
| 120 | The most important thing to understand about CTF, for barectf use |
| 121 | cases, is the layout of a binary stream packet: |
| 122 | |
| 123 | * Packet header (defined at the trace level) |
| 124 | * Packet context (defined at the stream level) |
| 125 | * Sequence of events (defined at the stream level): |
| 126 | * Event header (defined at the stream level) |
| 127 | * Stream event context (defined at the stream level) |
| 128 | * Event context (defined at the event level) |
| 129 | * Event payload (defined at the event level) |
| 130 | |
| 131 | The following diagram, stolen without remorse from CTF's website, shows |
| 132 | said packet layout: |
| 133 | |
| 134 | ![](http://diamon.org/ctf/img/ctf-stream-packet.png) |
| 135 | |
| 136 | Any of those six dynamic scopes, if defined at all, has an associated |
| 137 | CTF type. barectf requires them to be structure types. |
| 138 | |
| 139 | |
| 140 | ## Using |
| 141 | |
| 142 | See the [project's wiki](https://github.com/efficios/barectf/wiki) which |
| 143 | contains all the information needed to use barectf. |
| 144 | |
| 145 | |
| 146 | ## Testing |
| 147 | |
| 148 | Bash is required for testing barectf. |
| 149 | |
| 150 | The barectf tests execute the `barectf` command available in your |
| 151 | `$PATH`. The best way to test a specific version of barectf is to create |
| 152 | a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/), |
| 153 | install the appropriate version, and then run the tests. |
| 154 | |
| 155 | In the barectf source tree root, do: |
| 156 | |
| 157 | virtualenv --python=python3 virt |
| 158 | . ./virt/bin/activate |
| 159 | rehash # if using zsh |
| 160 | ./setup.py install |
| 161 | (cd tests && ./test.bash) |
| 162 | |
| 163 | You can specify [Bats](https://github.com/sstephenson/bats) options to |
| 164 | `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/) |
| 165 | output. |
| 166 | |
| 167 | You can exit the virtual environment by running `deactivate`. |
| 168 | |
| 169 | |
| 170 | ## Community |
| 171 | |
| 172 | Since the barectf community is small, it's sharing the communication |
| 173 | channels of the [LTTng](http://lttng.org/) project, |
| 174 | as [EfficiOS](http://www.efficios.com/) is the main sponsor of both |
| 175 | projects. It goes like this: |
| 176 | |
| 177 | | Item | Location | Notes | |
| 178 | | --- | --- | --- | |
| 179 | | Mailing list | [lttng-dev](https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev) (`lttng-dev@lists.lttng.org`) | Preferably, use the `[barectf]` subject prefix | |
| 180 | | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode | |
| 181 | | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | | |
| 182 | | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | | |
| 183 | | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | | |
| 184 | | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | | |