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