| 1 | // Render with Asciidoctor |
| 2 | |
| 3 | = Babeltrace |
| 4 | 13 April 2020 |
| 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://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API], |
| 19 | https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], |
| 20 | and a |
| 21 | https://babeltrace.org/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://babeltrace.org[official website], in |
| 33 | particular the |
| 34 | https://babeltrace.org/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 2020, {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://babeltrace.org/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}{nbsp}C{nbsp}API HTML documentation**_:: |
| 95 | * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6 |
| 96 | |
| 97 | _**If you need the {bt2} manual pages**_:: |
| 98 | * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 |
| 99 | * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25 |
| 100 | |
| 101 | _**If you need the `bt2` Python bindings documentation**_:: |
| 102 | * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for |
| 103 | Python{nbsp}3 |
| 104 | (Debian/Ubuntu/Fedora: `python3-sphinx`) |
| 105 | |
| 106 | |
| 107 | === Procedure |
| 108 | |
| 109 | To build {bt2}: |
| 110 | |
| 111 | . **If you build from a Git clone**, do: |
| 112 | + |
| 113 | [role="term"] |
| 114 | ---- |
| 115 | $ ./bootstrap |
| 116 | ---- |
| 117 | + |
| 118 | This generates the `configure` script and other important files. |
| 119 | |
| 120 | . [[conf]]Configure the project: |
| 121 | + |
| 122 | [role="term"] |
| 123 | ---- |
| 124 | $ ./configure |
| 125 | ---- |
| 126 | + |
| 127 | -- |
| 128 | The following options can modify the build: |
| 129 | |
| 130 | `--enable-api-doc`:: |
| 131 | Build the {bt2}{nbsp}C{nbsp}API HTML documentation. |
| 132 | |
| 133 | `--enable-debug-info`:: |
| 134 | Build the https://lttng.org/[LTTng] debug information filter |
| 135 | component class |
| 136 | (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). |
| 137 | |
| 138 | `--enable-man-pages`:: |
| 139 | Build the {bt2} manual pages. |
| 140 | |
| 141 | `--enable-python-bindings`:: |
| 142 | Build the `bt2` Python bindings. |
| 143 | + |
| 144 | You can set the path to custom `python3` and `python3-config` programs |
| 145 | with the `PYTHON` and `PYTHON_CONFIG` environment variable. |
| 146 | |
| 147 | `--enable-python-bindings-doc`:: |
| 148 | Build the `bt2` Python bindings documentation. |
| 149 | |
| 150 | `--enable-python-plugins`:: |
| 151 | Build support for {bt2} Python plugins. |
| 152 | |
| 153 | The following environment variables can modify the build: |
| 154 | |
| 155 | `BABELTRACE_DEBUG_MODE`:: |
| 156 | Set to `1` to enable the debug mode. |
| 157 | + |
| 158 | The debug mode enables more run-time assertions to detect bugs in the |
| 159 | {bt2} project. |
| 160 | |
| 161 | `BABELTRACE_DEV_MODE`:: |
| 162 | Set to `1` to enable the <<dev-mode,developer mode>>. |
| 163 | + |
| 164 | The {bt2} developer mode enables more precondition and postcondition |
| 165 | assertions to detect programming errors. |
| 166 | |
| 167 | `BABELTRACE_MINIMAL_LOG_LEVEL`:: |
| 168 | Set the build-time, minimal logging level for all the project's |
| 169 | modules. |
| 170 | + |
| 171 | Set to `TRACE`, `DEBUG`, or `INFO`. |
| 172 | |
| 173 | `BABELTRACE_PLUGIN_PROVIDERS_DIR`:: |
| 174 | Installation directory of {bt2} plugin providers. |
| 175 | |
| 176 | `BABELTRACE_PLUGINS_DIR`:: |
| 177 | Installation directory of {bt2} project plugins. |
| 178 | |
| 179 | See `./configure --help` to list all the available options and |
| 180 | environment variables. |
| 181 | -- |
| 182 | |
| 183 | . Build {bt2}: |
| 184 | + |
| 185 | [role="term"] |
| 186 | ---- |
| 187 | $ make |
| 188 | ---- |
| 189 | |
| 190 | To install {bt2}: |
| 191 | |
| 192 | * Do: |
| 193 | + |
| 194 | [role="term"] |
| 195 | ---- |
| 196 | # make install |
| 197 | ---- |
| 198 | |
| 199 | |
| 200 | [[dev-mode]] |
| 201 | === Build {bt2} for plugin or application development |
| 202 | |
| 203 | If you are developing a {bt2} plugin or an application which uses |
| 204 | libbabeltrace2, we recommend that: |
| 205 | |
| 206 | * You build {bt2} from source in _developer mode_. |
| 207 | + |
| 208 | The {bt2} developer mode enables more precondition and postcondition |
| 209 | assertions to detect programming errors. |
| 210 | + |
| 211 | Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build. |
| 212 | |
| 213 | * You use _TRACE_ as the minimal logging level at build time to have |
| 214 | access to more logging, should you need it to debug your plugin or |
| 215 | application. |
| 216 | + |
| 217 | Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>> |
| 218 | the {bt2} build. |
| 219 | |
| 220 | {bt2} development build configuration command line example: |
| 221 | |
| 222 | [role="term"] |
| 223 | ---- |
| 224 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure |
| 225 | ---- |
| 226 | |
| 227 | {bt2} development build configuration with Python support example: |
| 228 | |
| 229 | [role="term"] |
| 230 | ---- |
| 231 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ |
| 232 | --enable-python-bindings --enable-python-plugins |
| 233 | ---- |
| 234 | |
| 235 | See the |
| 236 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] |
| 237 | documentation for more information. |
| 238 | |
| 239 | |
| 240 | == Use Babeltrace{nbsp}{btversion} |
| 241 | |
| 242 | See the https://babeltrace.org[Babeltrace website] to learn how |
| 243 | to use the different parts of the project. |
| 244 | |
| 245 | |
| 246 | === Run-time requirements |
| 247 | |
| 248 | Libraries:: |
| 249 | * A C library (for example, |
| 250 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library], |
| 251 | https://www.musl-libc.org/[musl libc]) |
| 252 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
| 253 | (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) |
| 254 | |
| 255 | _**If you need the `bt2` Python bindings**_:: |
| 256 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 |
| 257 | (Debian/Ubuntu/Fedora: `python3`) |
| 258 | |
| 259 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: |
| 260 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 |
| 261 | (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and |
| 262 | `elfutils-libelf`) |
| 263 | |
| 264 | |
| 265 | == Community |
| 266 | |
| 267 | [NOTE] |
| 268 | ==== |
| 269 | Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and |
| 270 | pretty-print their events. |
| 271 | |
| 272 | Even though Babeltrace is independent from the LTTng project today, |
| 273 | their communities remain very close, which is why they share some |
| 274 | communication channels and services. |
| 275 | ==== |
| 276 | |
| 277 | Mailing list:: |
| 278 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] |
| 279 | (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) |
| 280 | |
| 281 | IRC channel:: |
| 282 | irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network |
| 283 | |
| 284 | Bug tracker:: |
| 285 | https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker] |
| 286 | |
| 287 | GitHub project:: |
| 288 | https://github.com/efficios/babeltrace/[efficios/babeltrace] |
| 289 | |
| 290 | Continuous integration:: |
| 291 | https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build] |
| 292 | on LTTng's CI |
| 293 | |
| 294 | Code review:: |
| 295 | https://review.lttng.org/q/project:babeltrace[_babeltrace_ project] |
| 296 | on LTTng Review |