Commit | Line | Data |
---|---|---|
fa62a451 | 1 | ![Icon made by Freepik from www.flaticon.com](https://lttng.org/blog/images/barectf.png) |
fffd4c7d | 2 | |
8be23338 | 3 | [![](https://img.shields.io/pypi/v/barectf.svg)](https://pypi.python.org/pypi/barectf) |
b7c42d35 | 4 | [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf.svg)](https://ci.lttng.org/job/barectf) |
8be23338 | 5 | |
9d38bef3 | 6 | **barectf** is a command-line utility which generates C99 |
e5aa0be3 PP |
7 | code that is able to write native [Common Trace Format](http://diamon.org/ctf) |
8 | (CTF) binary streams. | |
fffd4c7d PP |
9 | |
10 | You will find barectf interesting if: | |
11 | ||
e5aa0be3 PP |
12 | 1. You need to trace an application. |
13 | 2. You need tracing to be efficient, yet flexible: | |
fffd4c7d | 14 | record integers of custom sizes, custom floating point numbers, |
e5aa0be3 PP |
15 | enumerations supported by a specific integer type, and |
16 | null-terminated UTF-8/ASCII strings (C strings). | |
fffd4c7d PP |
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 | |
cb25d862 | 19 | ([Babeltrace](http://diamon.org/babeltrace/) does all that, |
fffd4c7d PP |
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 | |
e5aa0be3 | 23 | also outputs CTF. |
fffd4c7d PP |
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 | |
e5aa0be3 | 27 | is pure C99 and can be lightweight enough to fit on a tiny microcontroller. |
fffd4c7d | 28 | |
e5aa0be3 | 29 | **Key features**: |
fffd4c7d | 30 | |
9d38bef3 PP |
31 | * Single input: easy-to-write [YAML configuration |
32 | file](https://github.com/efficios/barectf/wiki/Writing-the-YAML-configuration-file) | |
e5aa0be3 | 33 | * 1-to-1 mapping from tracing function parameters to event fields |
9d38bef3 PP |
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.: | |
e5aa0be3 PP |
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 | |
fffd4c7d | 49 | |
e5aa0be3 | 50 | **Current limitations**: |
fffd4c7d | 51 | |
e5aa0be3 PP |
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. | |
de9eae2c PP |
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. | |
e5aa0be3 PP |
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**: | |
fffd4c7d | 81 | |
3e57f21a PP |
82 | It is recommended to use the |
83 | [barectf PPA](https://launchpad.net/~lttng/+archive/ubuntu/barectf), | |
84 | which also installs the man page: | |
85 | ||
86 | sudo apt-add-repository ppa:lttng/barectf | |
87 | sudo apt-get update | |
88 | sudo apt-get install barectf | |
89 | ||
90 | Otherwise, you can always use `pip3`: | |
91 | ||
fffd4c7d | 92 | sudo apt-get install python3-pip |
e5aa0be3 | 93 | sudo pip3 install barectf |
fffd4c7d | 94 | |
e5aa0be3 | 95 | **Ubuntu 12.04 and lower**: |
fffd4c7d PP |
96 | |
97 | sudo apt-get install python3-setuptools | |
98 | sudo easy_install3 pip | |
e5aa0be3 | 99 | sudo pip3 install barectf |
fffd4c7d | 100 | |
e5aa0be3 | 101 | **Debian**: |
fffd4c7d | 102 | |
e5aa0be3 | 103 | sudo apt-get install python3-pip |
fffd4c7d PP |
104 | sudo pip3 install barectf |
105 | ||
e5aa0be3 | 106 | **Fedora 20 and up**: |
fffd4c7d | 107 | |
e5aa0be3 PP |
108 | sudo yum install python3-pip |
109 | sudo pip3 install barectf | |
fffd4c7d | 110 | |
e5aa0be3 | 111 | **Arch Linux**: |
fffd4c7d | 112 | |
42eba90e PP |
113 | It is recommended to use the |
114 | [AUR package](https://aur.archlinux.org/packages/barectf/), which also | |
115 | installs the man page. If you have | |
116 | [yaourt](https://archlinux.fr/yaourt-en): | |
117 | ||
118 | sudo yaourt -Sy barectf | |
119 | ||
120 | Otherwise, you can always use `pip`: | |
121 | ||
c119e70b | 122 | sudo pacman -S python-pip |
e5aa0be3 | 123 | sudo pip install barectf |
fffd4c7d | 124 | |
3e57f21a | 125 | **OS X**: |
fffd4c7d | 126 | |
e5aa0be3 | 127 | With [Homebrew](http://brew.sh/): |
ca3417e6 | 128 | |
e5aa0be3 PP |
129 | brew install python3 |
130 | pip3 install barectf | |
fffd4c7d | 131 | |
fffd4c7d | 132 | |
b4d4665f PP |
133 | ### Man page |
134 | ||
2a86ff15 | 135 | Since the philosophy of setuptools packages is to include everything |
b4d4665f PP |
136 | within the package, the barectf man page is not installed on the system |
137 | when installing barectf with `pip` or with `setup.py`. This would be the | |
138 | job of distribution packages. | |
139 | ||
140 | You can install it manually: | |
141 | ||
142 | wget https://raw.githubusercontent.com/efficios/barectf/vVERSION/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1 | |
143 | ||
144 | Replace `VERSION` with the desired version, for example: | |
145 | ||
146 | wget https://raw.githubusercontent.com/efficios/barectf/v2.1.4/doc/man/barectf.1 -O /usr/local/man/man1/barectf.1 | |
147 | ||
148 | ||
e5aa0be3 | 149 | ## What is CTF? |
fffd4c7d | 150 | |
e5aa0be3 PP |
151 | See the [CTF in a nutshell](http://diamon.org/ctf/#ctf-in-a-nutshell) |
152 | section of CTF's website to understand the basics of this | |
153 | trace format. | |
fffd4c7d | 154 | |
e5aa0be3 PP |
155 | The most important thing to understand about CTF, for barectf use |
156 | cases, is the layout of a binary stream packet: | |
fffd4c7d | 157 | |
e5aa0be3 PP |
158 | * Packet header (defined at the trace level) |
159 | * Packet context (defined at the stream level) | |
160 | * Sequence of events (defined at the stream level): | |
161 | * Event header (defined at the stream level) | |
162 | * Stream event context (defined at the stream level) | |
163 | * Event context (defined at the event level) | |
164 | * Event payload (defined at the event level) | |
fffd4c7d | 165 | |
e5aa0be3 PP |
166 | The following diagram, stolen without remorse from CTF's website, shows |
167 | said packet layout: | |
fffd4c7d | 168 | |
e5aa0be3 | 169 | ![](http://diamon.org/ctf/img/ctf-stream-packet.png) |
fffd4c7d | 170 | |
e5aa0be3 PP |
171 | Any of those six dynamic scopes, if defined at all, has an associated |
172 | CTF type. barectf requires them to be structure types. | |
fffd4c7d | 173 | |
fffd4c7d | 174 | |
e5aa0be3 | 175 | ## Using |
fffd4c7d | 176 | |
9d38bef3 PP |
177 | See the [project's wiki](https://github.com/efficios/barectf/wiki) which |
178 | contains all the information needed to use barectf. | |
bed7233f PP |
179 | |
180 | ||
181 | ## Testing | |
182 | ||
183 | Bash is required for testing barectf. | |
184 | ||
185 | The barectf tests execute the `barectf` command available in your | |
186 | `$PATH`. The best way to test a specific version of barectf is to create | |
187 | a Python 3 [virtual environment](https://virtualenv.pypa.io/en/latest/), | |
188 | install the appropriate version, and then run the tests. | |
189 | ||
190 | In the barectf source tree root, do: | |
191 | ||
e23f0269 | 192 | virtualenv --python=python3 virt |
bed7233f PP |
193 | . ./virt/bin/activate |
194 | rehash # if using zsh | |
195 | ./setup.py install | |
196 | (cd tests && ./test.bash) | |
197 | ||
198 | You can specify [Bats](https://github.com/sstephenson/bats) options to | |
199 | `./test.bash`, like `--tap` to get a [TAP](https://testanything.org/) | |
200 | output. | |
201 | ||
202 | You can exit the virtual environment by running `deactivate`. | |
5682f231 PP |
203 | |
204 | ||
205 | ## Community | |
206 | ||
207 | Since the barectf community is small, it's sharing the communication | |
208 | channels of the [LTTng](http://lttng.org/) project, | |
209 | as [EfficiOS](http://www.efficios.com/) is the main sponsor of both | |
210 | projects. It goes like this: | |
211 | ||
212 | | Item | Location | Notes | | |
213 | | --- | --- | --- | | |
214 | | 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 | | |
215 | | IRC | [`#lttng`](irc://irc.oftc.net/lttng) on the OFTC network | More specifically, query `eepp` (barectf's maintainer) on this network or on freenode | | |
216 | | Code contribution | Create a new GitHub [pull request](https://github.com/efficios/barectf/pulls) | | | |
217 | | Bug reporting | Create a new GitHub [issue](https://github.com/efficios/barectf/issues/new) | | | |
218 | | Continuous integration | [barectf item on LTTng's CI](https://ci.lttng.org/job/barectf/) | | | |
219 | | Blog | The [LTTng blog](http://lttng.org/blog/) contains many posts about barectf | | |