| 1 | // Render with Asciidoctor |
| 2 | |
| 3 | = Babeltrace |
| 4 | 15 October 2019 |
| 5 | :btversion: 2.0 |
| 6 | :bt2: Babeltrace{nbsp}2 |
| 7 | |
| 8 | |
| 9 | Babeltrace /ˈbæbəltreɪs/, an |
| 10 | https://efficios.com/[EfficiOS] project, is an open-source |
| 11 | https://en.wikipedia.org/wiki/Tracing_(software)[trace] |
| 12 | manipulation framework. |
| 13 | |
| 14 | https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]] |
| 15 | https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]] |
| 16 | |
| 17 | The **_{bt2}_** project offers a library with a |
| 18 | https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[C{nbsp}API], |
| 19 | https://diamon.org/babeltrace/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], |
| 20 | and a |
| 21 | https://diamon.org/babeltrace/docs/v{btversion}/man1/babeltrace2.1/[command-line tool] |
| 22 | (CLI) which makes it very easy for mere mortals to view, convert, |
| 23 | transform, and analyze traces. |
| 24 | |
| 25 | {bt2} is also the reference parser implementation of the |
| 26 | https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile |
| 27 | trace format produced by various tracers and tools such as |
| 28 | https://lttng.org/[LTTng] and |
| 29 | https://barectf.org/[barectf]. The {bt2} library and its Python bindings |
| 30 | can read and write CTF traces. |
| 31 | |
| 32 | See Babeltrace's https://diamon.org/babeltrace[official website], in |
| 33 | particular the |
| 34 | https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] |
| 35 | manual page, to learn more about the project. |
| 36 | |
| 37 | [NOTE] |
| 38 | .Babeltrace{nbsp}1 vs. {bt2} |
| 39 | ==== |
| 40 | The Babeltrace project exists since 2010. In 2019, {bt2} was |
| 41 | released. {bt2} is a complete rewrite of the library, Python |
| 42 | bindings, and CLI. It is plugin-based and offers much more features and |
| 43 | potential than Babeltrace{nbsp}1 while showing comparable performance. |
| 44 | |
| 45 | Because {bt2} is still a young major release, some |
| 46 | distributions still provide packages for the Babeltrace{nbsp}1 project. |
| 47 | Both projects can coexist on the same system as there are no common |
| 48 | files. |
| 49 | |
| 50 | This file documents the **{bt2}** project. |
| 51 | ==== |
| 52 | |
| 53 | |
| 54 | == Build Babeltrace{nbsp}{btversion} from source |
| 55 | |
| 56 | === Build-time requirements |
| 57 | |
| 58 | To build Babeltrace{nbsp}{btversion}, you need: |
| 59 | |
| 60 | Compiler:: |
| 61 | * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and |
| 62 | https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension] |
| 63 | support. |
| 64 | + |
| 65 | https://clang.llvm.org/[Clang] is one of those. |
| 66 | |
| 67 | Tools:: |
| 68 | * https://www.gnu.org/software/make/[GNU Make] |
| 69 | * **If you build from a Git clone**: |
| 70 | ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.10 |
| 71 | ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.64 |
| 72 | ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2 |
| 73 | ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35 |
| 74 | ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.4 |
| 75 | |
| 76 | Libraries:: |
| 77 | * A C library (for example, |
| 78 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library], |
| 79 | https://www.musl-libc.org/[musl libc]) |
| 80 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
| 81 | (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`) |
| 82 | |
| 83 | _**If you need the `bt2` Python bindings**_:: |
| 84 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development |
| 85 | libraries and `python3-config`) |
| 86 | (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`) |
| 87 | * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0 |
| 88 | |
| 89 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: |
| 90 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 |
| 91 | (Debian/Ubuntu: `libelf-dev` and `libdw-dev`; |
| 92 | Fedora: `elfutils-devel` and `elfutils-libelf-devel`) |
| 93 | |
| 94 | _**If you need the `bt2` Python bindings documentation**_:: |
| 95 | * Python{nbsp}≥{nbsp}3.4 |
| 96 | (Debian/Ubuntu/Fedora: `python3`) |
| 97 | * https://www.sphinx-doc.org/en/master/[Sphinx]{nbsp}≥{nbsp}1.6.5 |
| 98 | for Python{nbsp}3 (Debian/Ubuntu/Fedora: `python3-sphinx`) |
| 99 | |
| 100 | _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_:: |
| 101 | * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6 |
| 102 | |
| 103 | _**If you need the {bt2} manual pages**_:: |
| 104 | * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 |
| 105 | * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25 |
| 106 | |
| 107 | |
| 108 | === Procedure |
| 109 | |
| 110 | To build {bt2}: |
| 111 | |
| 112 | . **If you build from a Git clone**, do: |
| 113 | + |
| 114 | [role="term"] |
| 115 | ---- |
| 116 | $ ./bootstrap |
| 117 | ---- |
| 118 | + |
| 119 | This generates the `configure` script and other important files. |
| 120 | |
| 121 | . [[conf]]Configure the project: |
| 122 | + |
| 123 | [role="term"] |
| 124 | ---- |
| 125 | $ ./configure |
| 126 | ---- |
| 127 | + |
| 128 | -- |
| 129 | The following options can modify the build: |
| 130 | |
| 131 | `--enable-api-doc`:: |
| 132 | Build the {bt2}{nbsp}C{nbsp}API HTML documentation. |
| 133 | |
| 134 | `--enable-debug-info`:: |
| 135 | Build the https://lttng.org/[LTTng] debug information filter |
| 136 | component class |
| 137 | (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). |
| 138 | |
| 139 | `--enable-man-pages`:: |
| 140 | Build the {bt2} manual pages. |
| 141 | |
| 142 | `--enable-python-bindings`:: |
| 143 | Build the `bt2` Python bindings. |
| 144 | + |
| 145 | You can set the path to custom `python3` and `python3-config` programs |
| 146 | with the `PYTHON` and `PYTHON_CONFIG` environment variable. |
| 147 | |
| 148 | `--enable-python-bindings-doc`:: |
| 149 | Build the `bt2` Python bindings documentation. |
| 150 | |
| 151 | `--enable-python-plugins`:: |
| 152 | Build support for {bt2} Python plugins. |
| 153 | |
| 154 | The following environment variables can modify the build: |
| 155 | |
| 156 | `BABELTRACE_DEBUG_MODE`:: |
| 157 | Set to `1` to enable the debug mode. |
| 158 | + |
| 159 | The debug mode enables more run-time assertions to detect bugs in the |
| 160 | {bt2} project. |
| 161 | |
| 162 | `BABELTRACE_DEV_MODE`:: |
| 163 | Set to `1` to enable the <<dev-mode,developer mode>>. |
| 164 | + |
| 165 | The {bt2} developer mode enables more precondition and postcondition |
| 166 | assertions to detect programming errors. |
| 167 | |
| 168 | `BABELTRACE_MINIMAL_LOG_LEVEL`:: |
| 169 | Set the build-time, minimal logging level for all the project's |
| 170 | modules. |
| 171 | + |
| 172 | Set to `TRACE`, `DEBUG`, or `INFO`. |
| 173 | |
| 174 | `BABELTRACE_PLUGIN_PROVIDERS_DIR`:: |
| 175 | Installation directory of {bt2} plugin providers. |
| 176 | |
| 177 | `BABELTRACE_PLUGINS_DIR`:: |
| 178 | Installation directory of {bt2} project plugins. |
| 179 | |
| 180 | See `./configure --help` to list all the available options and |
| 181 | environment variables. |
| 182 | -- |
| 183 | |
| 184 | . Build {bt2}: |
| 185 | + |
| 186 | [role="term"] |
| 187 | ---- |
| 188 | $ make |
| 189 | ---- |
| 190 | |
| 191 | To install {bt2}: |
| 192 | |
| 193 | * Do: |
| 194 | + |
| 195 | [role="term"] |
| 196 | ---- |
| 197 | # make install |
| 198 | ---- |
| 199 | |
| 200 | |
| 201 | [[dev-mode]] |
| 202 | === Build {bt2} for plugin or application development |
| 203 | |
| 204 | If you are developing a {bt2} plugin or an application which uses |
| 205 | libbabeltrace2, we recommend that: |
| 206 | |
| 207 | * You build {bt2} from source in _developer mode_. |
| 208 | + |
| 209 | The {bt2} developer mode enables more precondition and postcondition |
| 210 | assertions to detect programming errors. |
| 211 | + |
| 212 | Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build. |
| 213 | |
| 214 | * You use _TRACE_ as the minimal logging level at build time to have |
| 215 | access to more logging, should you need it to debug your plugin or |
| 216 | application. |
| 217 | + |
| 218 | Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>> |
| 219 | the {bt2} build. |
| 220 | |
| 221 | {bt2} development build configuration command line example: |
| 222 | |
| 223 | [role="term"] |
| 224 | ---- |
| 225 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure |
| 226 | ---- |
| 227 | |
| 228 | {bt2} development build configuration with Python support example: |
| 229 | |
| 230 | [role="term"] |
| 231 | ---- |
| 232 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ |
| 233 | --enable-python-bindings --enable-python-plugins |
| 234 | ---- |
| 235 | |
| 236 | See the |
| 237 | https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] |
| 238 | documentation for more information. |
| 239 | |
| 240 | |
| 241 | == Use Babeltrace{nbsp}{btversion} |
| 242 | |
| 243 | See the https://diamon.org/babeltrace[Babeltrace website] to learn how |
| 244 | to use the different parts of the project. |
| 245 | |
| 246 | |
| 247 | === Run-time requirements |
| 248 | |
| 249 | Libraries:: |
| 250 | * A C library (for example, |
| 251 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library], |
| 252 | https://www.musl-libc.org/[musl libc]) |
| 253 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
| 254 | (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) |
| 255 | |
| 256 | _**If you need the `bt2` Python bindings**_:: |
| 257 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 |
| 258 | (Debian/Ubuntu/Fedora: `python3`) |
| 259 | |
| 260 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: |
| 261 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 |
| 262 | (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and |
| 263 | `elfutils-libelf`) |
| 264 | |
| 265 | |
| 266 | == Community |
| 267 | |
| 268 | [NOTE] |
| 269 | ==== |
| 270 | Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and |
| 271 | pretty-print their events. |
| 272 | |
| 273 | Even though Babeltrace is independant from the LTTng project today, |
| 274 | their communities remain very close, which is why they share some |
| 275 | communication channels and services. |
| 276 | ==== |
| 277 | |
| 278 | Mailing list:: |
| 279 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] |
| 280 | (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) |
| 281 | |
| 282 | IRC channel:: |
| 283 | irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network |
| 284 | |
| 285 | Bug tracker:: |
| 286 | https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker] |
| 287 | |
| 288 | GitHub project:: |
| 289 | https://github.com/efficios/babeltrace/[efficios/babeltrace] |
| 290 | |
| 291 | Continuous integration:: |
| 292 | https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build] |
| 293 | on LTTng's CI |
| 294 | |
| 295 | Code review:: |
| 296 | https://review.lttng.org/q/project:babeltrace[_babeltrace_ project] |
| 297 | on LTTng Review |