| 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_master_build.svg)](https://ci.lttng.org/job/barectf_master_build) |
| 5 | |
| 6 | _**barectf**_ is a command-line generator of ANSI C tracers which output |
| 7 | [Common Trace Format](http://diamon.org/ctf) packets natively. |
| 8 | |
| 9 | You will find barectf interesting if: |
| 10 | |
| 11 | 1. You need to trace an application. |
| 12 | 2. You need tracing to be efficient, yet flexible: record integers of |
| 13 | custom sizes and alignments, floating point numbers, enumerations |
| 14 | supported by a specific integer type, and null-terminated |
| 15 | UTF-8/ASCII strings (C strings). |
| 16 | 3. You need to be able to convert the recorded binary events to |
| 17 | human-readable text, as well as analyze them with Python scripts |
| 18 | ([Babeltrace](http://diamon.org/babeltrace/) does all that, |
| 19 | given a CTF input). [Trace Compass](http://tracecompass.org/) is |
| 20 | another CTF-compatible application. |
| 21 | 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing |
| 22 | framework for the Linux kernel and Linux/BSD user applications, |
| 23 | which also outputs CTF traces. |
| 24 | |
| 25 | The target audience of barectf is developers who need to trace [bare |
| 26 | metal](https://en.wikipedia.org/wiki/Bare_machine) systems. The code |
| 27 | produced by barectf is pure ANCI C (with one exception, see the current |
| 28 | limitations below) and can be lightweight enough to fit on a tiny |
| 29 | microcontroller. |
| 30 | |
| 31 | **Key features**: |
| 32 | |
| 33 | * Single input: easy-to-write [YAML configuration |
| 34 | file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file). |
| 35 | * 1-to-1 mapping from tracing function parameters to event fields. |
| 36 | * Custom and bundled |
| 37 | [_platforms_](https://github.com/efficios/barectf/wiki/barectf-platform) |
| 38 | hiding the details of opening/closing packets and writing them to a |
| 39 | back-end (continuous tracing), getting the clock values, etc.: |
| 40 | * _linux-fs_: basic Linux application tracing platform which writes |
| 41 | stream files to the file system for demonstration purposes. |
| 42 | * _parallella_: Adapteva |
| 43 | Epiphany/[Parallella](http://parallella.org/) with host-side |
| 44 | consumer. |
| 45 | * CTF metadata is generated by the command-line tool (automatic trace |
| 46 | UUID, stream IDs, and event IDs). |
| 47 | * All basic CTF types are supported: integers, floating point numbers, |
| 48 | enumerations, and null-terminated strings (C strings). |
| 49 | * Binary streams produced by the generated tracer and metadata file |
| 50 | produced by barectf are CTF 1.8-compliant. |
| 51 | * Human-readable error reporting at generation time. |
| 52 | * barectf is written in Python 3, hence you can run the tool on |
| 53 | various platforms. |
| 54 | * Generated tracers are known to build with `gcc` (tested with the |
| 55 | IA-32, x86-64, MIPS, ARM, and AVR architectures), `g++`, `clang`, |
| 56 | `clang++`, [`8cc`](https://github.com/rui314/8cc), |
| 57 | [`tcc`](http://bellard.org/tcc/), VS2008 (with a custom `stdint.h`), |
| 58 | and VS2010. |
| 59 | |
| 60 | **Current limitations**: |
| 61 | |
| 62 | As of this version: |
| 63 | |
| 64 | * All the generated tracing C functions, for a given barectf |
| 65 | stream-specific context, need to be called from the same thread, and |
| 66 | cannot be called from an interrupt handler, _unless_ a user-provided |
| 67 | synchronization mechanism is used. |
| 68 | * The generated C code needs the `stdint.h` header, which is new in |
| 69 | C99. If your standard C library does not have this header, |
| 70 | you can create one yourself and put it in one of your include |
| 71 | directories to define the following types according to your |
| 72 | architecture: |
| 73 | * `int8_t` |
| 74 | * `int16_t` |
| 75 | * `int32_t` |
| 76 | * `int64_t` |
| 77 | * `uint8_t` |
| 78 | * `uint16_t` |
| 79 | * `uint32_t` |
| 80 | * `uint64_t` |
| 81 | * CTF compound types (array, sequence, structure, variant) are not |
| 82 | supported yet, except at some very specific locations in the |
| 83 | metadata. |
| 84 | |
| 85 | |
| 86 | ## Installing |
| 87 | |
| 88 | Make sure you have Python 3 and `pip` for Python 3 installed, then |
| 89 | install barectf. |
| 90 | |
| 91 | Note that you may pass the `--user` argument to |
| 92 | `pip install` to install the tool in your home directory (instead of |
| 93 | installing globally). |
| 94 | |
| 95 | **Ubuntu 14.04 and 16.04**: |
| 96 | |
| 97 | It is recommended to use the |
| 98 | [barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf), |
| 99 | which also installs the man page: |
| 100 | |
| 101 | sudo apt-add-repository ppa:lttng/barectf |
| 102 | sudo apt-get update |
| 103 | sudo apt-get install python3-barectf |
| 104 | |
| 105 | Otherwise, you can always use `pip3`: |
| 106 | |
| 107 | sudo apt-get install python3-pip |
| 108 | sudo pip3 install barectf |
| 109 | |
| 110 | **Other, recent Ubuntu**: |
| 111 | |
| 112 | sudo apt-get install python3-pip |
| 113 | sudo pip3 install barectf |
| 114 | |
| 115 | **Ubuntu 12.04 and lower**: |
| 116 | |
| 117 | sudo apt-get install python3-setuptools |
| 118 | sudo easy_install3 pip |
| 119 | sudo pip3 install barectf |
| 120 | |
| 121 | **Debian**: |
| 122 | |
| 123 | sudo apt-get install python3-pip |
| 124 | sudo pip3 install barectf |
| 125 | |
| 126 | **Fedora 20 and up**: |
| 127 | |
| 128 | sudo yum install python3-pip |
| 129 | sudo pip3 install barectf |
| 130 | |
| 131 | **Arch Linux**: |
| 132 | |
| 133 | It is recommended to use the |
| 134 | [AUR package](https://aur.archlinux.org/packages/barectf/), which also |
| 135 | installs the man page. If you have |
| 136 | [yaourt](https://archlinux.fr/yaourt-en): |
| 137 | |
| 138 | sudo yaourt -Sy barectf |
| 139 | |
| 140 | Otherwise, you can always use `pip`: |
| 141 | |
| 142 | sudo pacman -S python-pip |
| 143 | sudo pip install barectf |
| 144 | |
| 145 | **macOS (OS X)**: |
| 146 | |
| 147 | With [Homebrew](http://brew.sh/): |
| 148 | |
| 149 | brew install python3 |
| 150 | pip3 install barectf |
| 151 | |
| 152 | |
| 153 | ### Man page |
| 154 | |
| 155 | Since the philosophy of setuptools packages is to include everything |
| 156 | within the package, the barectf man page is not installed on the system |
| 157 | when installing barectf with `pip` or with `setup.py`. This would be the |
| 158 | job of distribution packages. |
| 159 | |
| 160 | You can install it manually: |
| 161 | |
| 162 | wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1 |
| 163 | |
| 164 | Replace `VERSION` with the desired version, for example: |
| 165 | |
| 166 | wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1 |
| 167 | |
| 168 | |
| 169 | ## What is CTF? |
| 170 | |
| 171 | See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell) |
| 172 | section of CTF's website to understand the basics of this |
| 173 | trace format. |
| 174 | |
| 175 | The most important thing to understand about CTF, for barectf use |
| 176 | cases, is the layout of a binary stream packet: |
| 177 | |
| 178 | * Packet header (defined at the trace level) |
| 179 | * Packet context (defined at the stream level) |
| 180 | * Sequence of events (defined at the stream level): |
| 181 | * Event header (defined at the stream level) |
| 182 | * Stream event context (defined at the stream level) |
| 183 | * Event context (defined at the event level) |
| 184 | * Event payload (defined at the event level) |
| 185 | |
| 186 | The following diagram, stolen without remorse from CTF's website, shows |
| 187 | said packet layout: |
| 188 | |
| 189 | ![](http://diamon.org/ctf/img/ctf-stream-packet.png) |
| 190 | |
| 191 | Any of those six dynamic scopes, if defined at all, has an associated |
| 192 | CTF type. barectf requires them to be structure types. |
| 193 | |
| 194 | |
| 195 | ## Using |
| 196 | |
| 197 | See the [project's wiki](https://github.com/efficios/barectf/wiki) which |
| 198 | contains all the information needed to use barectf. |
| 199 | |
| 200 | |
| 201 | ## Testing |
| 202 | |
| 203 | Bash is required for testing barectf. |
| 204 | |
| 205 | The barectf tests execute the `barectf` command available in your |
| 206 | `$PATH`. The best way to test a specific version of barectf is to create |
| 207 | a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/), |
| 208 | install the appropriate version, and then run the tests. |
| 209 | |
| 210 | In the barectf source tree root, do: |
| 211 | |
| 212 | virtualenv --python=python3 virt |
| 213 | . ./virt/bin/activate |
| 214 | rehash # if using zsh |
| 215 | ./setup.py install |
| 216 | (cd tests && ./test.bash) |
| 217 | |
| 218 | You can specify [Bats](https://github.com/sstephenson/bats) options to |
| 219 | `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/) |
| 220 | output. |
| 221 | |
| 222 | You can exit the virtual environment by running `deactivate`. |
| 223 | |
| 224 | |
| 225 | ## Community |
| 226 | |
| 227 | Since the barectf community is small, it's sharing the communication |
| 228 | channels of the [LTTng](http://lttng.org/) project, |
| 229 | as [EfficiOS](http://www.efficios.com/) is the main sponsor of both |
| 230 | projects. It goes like this: |
| 231 | |
| 232 | | Item | Location | Notes | |
| 233 | | --- | --- | --- | |
| 234 | | 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 | |
| 235 | | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode | |
| 236 | | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | | |
| 237 | | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | | |
| 238 | | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | | |
| 239 | | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | | |