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