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) |
383f81c9 | 4 | [![Jenkins](https://img.shields.io/jenkins/s/https/ci.lttng.org/barectf_master_build.svg)](https://ci.lttng.org/job/barectf_master_build) |
8be23338 | 5 | |
033bfe31 PP |
6 | _**barectf**_ is a command-line generator of ANSI C tracers which output |
7 | [Common Trace Format](http://diamon.org/ctf) packets natively. | |
fffd4c7d PP |
8 | |
9 | You will find barectf interesting if: | |
10 | ||
e5aa0be3 | 11 | 1. You need to trace an application. |
033bfe31 PP |
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). | |
fffd4c7d PP |
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 | |
cb25d862 | 18 | ([Babeltrace](http://diamon.org/babeltrace/) does all that, |
033bfe31 PP |
19 | given a CTF input). [Trace Compass](http://tracecompass.org/) is |
20 | another CTF-compatible application. | |
fffd4c7d | 21 | 4. You _cannot_ use [LTTng](http://lttng.org/), an efficient tracing |
033bfe31 PP |
22 | framework for the Linux kernel and Linux/BSD user applications, |
23 | which also outputs CTF traces. | |
fffd4c7d | 24 | |
033bfe31 PP |
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. | |
fffd4c7d | 30 | |
e5aa0be3 | 31 | **Key features**: |
fffd4c7d | 32 | |
9d38bef3 | 33 | * Single input: easy-to-write [YAML configuration |
033bfe31 PP |
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. | |
9d38bef3 PP |
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.: | |
033bfe31 PP |
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). | |
e5aa0be3 | 47 | * All basic CTF types are supported: integers, floating point numbers, |
033bfe31 PP |
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`, | |
7e82a458 PP |
56 | `clang++`, [`8cc`](https://github.com/rui314/8cc), |
57 | [`tcc`](http://bellard.org/tcc/), VS2008 (with a custom `stdint.h`), | |
033bfe31 | 58 | and VS2010. |
fffd4c7d | 59 | |
e5aa0be3 | 60 | **Current limitations**: |
fffd4c7d | 61 | |
e5aa0be3 PP |
62 | As of this version: |
63 | ||
64 | * All the generated tracing C functions, for a given barectf | |
033bfe31 PP |
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 | |
e5aa0be3 | 67 | synchronization mechanism is used. |
52507059 PP |
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. | |
e5aa0be3 | 84 | |
e5aa0be3 PP |
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 | ||
192a1cfb | 95 | **Ubuntu 14.04 and 16.04**: |
fffd4c7d | 96 | |
3e57f21a PP |
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 | |
091d7377 | 103 | sudo apt-get install python3-barectf |
3e57f21a PP |
104 | |
105 | Otherwise, you can always use `pip3`: | |
106 | ||
fffd4c7d | 107 | sudo apt-get install python3-pip |
192a1cfb PP |
108 | sudo pip3 install barectf |
109 | ||
110 | **Other, recent Ubuntu**: | |
111 | ||
112 | sudo apt-get install python3-pip | |
e5aa0be3 | 113 | sudo pip3 install barectf |
fffd4c7d | 114 | |
e5aa0be3 | 115 | **Ubuntu 12.04 and lower**: |
fffd4c7d PP |
116 | |
117 | sudo apt-get install python3-setuptools | |
118 | sudo easy_install3 pip | |
e5aa0be3 | 119 | sudo pip3 install barectf |
fffd4c7d | 120 | |
e5aa0be3 | 121 | **Debian**: |
fffd4c7d | 122 | |
e5aa0be3 | 123 | sudo apt-get install python3-pip |
fffd4c7d PP |
124 | sudo pip3 install barectf |
125 | ||
e5aa0be3 | 126 | **Fedora 20 and up**: |
fffd4c7d | 127 | |
e5aa0be3 PP |
128 | sudo yum install python3-pip |
129 | sudo pip3 install barectf | |
fffd4c7d | 130 | |
e5aa0be3 | 131 | **Arch Linux**: |
fffd4c7d | 132 | |
42eba90e PP |
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 | ||
c119e70b | 142 | sudo pacman -S python-pip |
e5aa0be3 | 143 | sudo pip install barectf |
fffd4c7d | 144 | |
033bfe31 | 145 | **macOS (OS X)**: |
fffd4c7d | 146 | |
e5aa0be3 | 147 | With [Homebrew](http://brew.sh/): |
ca3417e6 | 148 | |
e5aa0be3 PP |
149 | brew install python3 |
150 | pip3 install barectf | |
fffd4c7d | 151 | |
fffd4c7d | 152 | |
b4d4665f PP |
153 | ### Man page |
154 | ||
2a86ff15 | 155 | Since the philosophy of setuptools packages is to include everything |
b4d4665f PP |
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 | ||
e5aa0be3 | 169 | ## What is CTF? |
fffd4c7d | 170 | |
e5aa0be3 PP |
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. | |
fffd4c7d | 174 | |
e5aa0be3 PP |
175 | The most important thing to understand about CTF, for barectf use |
176 | cases, is the layout of a binary stream packet: | |
fffd4c7d | 177 | |
e5aa0be3 PP |
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) | |
fffd4c7d | 185 | |
e5aa0be3 PP |
186 | The following diagram, stolen without remorse from CTF's website, shows |
187 | said packet layout: | |
fffd4c7d | 188 | |
e5aa0be3 | 189 | ![](http://diamon.org/ctf/img/ctf-stream-packet.png) |
fffd4c7d | 190 | |
e5aa0be3 PP |
191 | Any of those six dynamic scopes, if defined at all, has an associated |
192 | CTF type. barectf requires them to be structure types. | |
fffd4c7d | 193 | |
fffd4c7d | 194 | |
e5aa0be3 | 195 | ## Using |
fffd4c7d | 196 | |
9d38bef3 PP |
197 | See the [project's wiki](https://github.com/efficios/barectf/wiki) which |
198 | contains all the information needed to use barectf. | |
bed7233f PP |
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 | ||
e23f0269 | 212 | virtualenv --python=python3 virt |
bed7233f PP |
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`. | |
5682f231 PP |
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 | | |