1 ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png)
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)
6 _**barectf**_ is a command-line generator of ANSI C tracers which output
7 [Common Trace Format](http://diamon.org/ctf) packets natively.
9 You will find barectf interesting if:
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.
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
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.
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
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
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`),
60 **Current limitations**:
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
81 * CTF compound types (array, sequence, structure, variant) are not
82 supported yet, except at some very specific locations in the
88 Make sure you have Python 3 and `pip` for Python 3 installed, then
91 Note that you may pass the `--user` argument to
92 `pip install` to install the tool in your home directory (instead of
95 **Ubuntu 14.04 and 16.04**:
97 It is recommended to use the
98 [barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf),
99 which also installs the man page:
101 sudo apt-add-repository ppa:lttng/barectf
103 sudo apt-get install python3-barectf
105 Otherwise, you can always use `pip3`:
107 sudo apt-get install python3-pip
108 sudo pip3 install barectf
110 **Other, recent Ubuntu**:
112 sudo apt-get install python3-pip
113 sudo pip3 install barectf
115 **Ubuntu 12.04 and lower**:
117 sudo apt-get install python3-setuptools
118 sudo easy_install3 pip
119 sudo pip3 install barectf
123 sudo apt-get install python3-pip
124 sudo pip3 install barectf
126 **Fedora 20 and up**:
128 sudo yum install python3-pip
129 sudo pip3 install barectf
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):
138 sudo yaourt -Sy barectf
140 Otherwise, you can always use `pip`:
142 sudo pacman -S python-pip
143 sudo pip install barectf
147 With [Homebrew](http://brew.sh/):
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.
160 You can install it manually:
162 wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
164 Replace `VERSION` with the desired version, for example:
166 wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1
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
175 The most important thing to understand about CTF, for barectf use
176 cases, is the layout of a binary stream packet:
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)
186 The following diagram, stolen without remorse from CTF's website, shows
189 ![](http://diamon.org/ctf/img/ctf-stream-packet.png)
191 Any of those six dynamic scopes, if defined at all, has an associated
192 CTF type. barectf requires them to be structure types.
197 See the [project's wiki](https://github.com/efficios/barectf/wiki) which
198 contains all the information needed to use barectf.
203 Bash is required for testing barectf.
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.
210 In the barectf source tree root, do:
212 virtualenv --python=python3 virt
213 . ./virt/bin/activate
214 rehash # if using zsh
216 (cd tests && ./test.bash)
218 You can specify [Bats](https://github.com/sstephenson/bats) options to
219 `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/)
222 You can exit the virtual environment by running `deactivate`.
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:
232 | Item | Location | Notes |
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 | |