BABELTRACE2-CONVERT(1)

📦
version 2.1.2 · 9 versions
, in fedora 43, fedora 44

🦋 babeltrace2-convert 🦋

part of the Babeltrace 2 manual

🌸 NAME 🌸

babeltrace2-convert — bestie, this is the glow-up machine: it takes one or more traces and converts them to a given format. 💅

✨ SYNOPSIS ✨

Okay so there's a whole handful of ways to call this, and each one is a different vibe. Sit with me:

Pretty-print (plain text) the events, in order, of one or more traces:

babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US]
            [--allowed-mip-versions=VERSION] TRACE-PATH...

Convert one or more traces to a given format:

babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US]
            [--allowed-mip-versions=VERSION] CONVERSION ARGS

Get the equivalent babeltrace2-run(1) command arguments to convert one or more traces to a given format:

babeltrace2 [GENERAL OPTIONS] [convert] [--retry-duration=TIME-US]
            [--allowed-mip-versions=VERSION]
            (--run-args | --run-args-0) CONVERSION ARGS

Print the metadata text of a CTF trace:

babeltrace2 [GENERAL OPTIONS] [convert] [--output=OUTPATH]
            --output-format=ctf-metadata TRACE-PATH

Print the available remote LTTng tracing sessions (the docs live over at <https://lttng.org/docs/#doc-lttng-live>, iykyk):

babeltrace2 [GENERAL OPTIONS] [convert] [--output=OUTPATH]
            --input-format=lttng-live URL

💖 DESCRIPTION 💖

The convert command takes one or more traces and converts them to a given format — and lowkey, it can run filters along the conversion path too. Filters in the middle? Iconic behavior.

Go read babeltrace2-intro(7) if you wanna learn more about the Babeltrace 2 project and its core concepts. 🫶

Note 📌 convert is the default babeltrace2(1) command, so most of the time you don't even have to say its name out loud. These two are literally equivalent — as long as the ... part doesn't start with the name of another babeltrace2(1) command, like run or list-plugins: $ babeltrace2 convert ... $ babeltrace2 ... But if you need to be 100% sure you're running the convert command? Then write babeltrace2 convert explicitly. No cap. 💅

More specifically, the convert command creates a conversion graph.

A conversion graph is a specialized trace processing graph focused on the conversion of one or more traces to another format, possibly filtering or modifying their events and other messages in the process. Once the source streams are merged, a conversion graph is a linear chain of components:

+----------+
| source 1 @-.
+----------+ |
             |  +-------+
+----------+ '->@       |    +---------+    +------------+
| source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-.
+----------+ .->@       |    +---------+    +------------+ |
             |  +-------+                                  |
+----------+ |    .----------------------------------------'
|   ...    @-'    |  +---------------+    +------+
+----------+      '->@ other filters |--->@ sink |
                     +---------------+    +------+

Note that the trimmer, the debugging information, and the other filters are optional. See "Create implicit components from options" to learn how to turn them on. ✨

If you need a different trace processing graph layout, then go use the more flexible babeltrace2-run(1) command instead.

Like with the babeltrace2-run(1) command, you can create components explicitly with the --component option (see "Create explicit components"). You can also use one of the many specific convert command options (see "Create implicit components from options") and non-option arguments (see "Create implicit components from non-option arguments") to create implicit components.

An implicit component is a component which is created and added to the conversion graph without an explicit instantiation through the --component option. An implicit component is easier to create than an explicit component — that's literally the whole reason the convert command exists, because you can also create and run a conversion graph with the generic babeltrace2-run(1) command. 💀

For example, you can specify one or more CTF trace paths as non-option arguments to pretty-print the merged events to the standard output:

$ babeltrace2 /path/to/trace /path/to/other/trace

That is the equivalent of creating and connecting together:

  • One source.ctf.fs components with its inputs initialization parameter set to /path/to/trace.
  • One source.ctf.fs components with its inputs initialization parameter set to /path/to/other/trace.
  • A filter.utils.muxer component.
  • A sink.text.pretty component.

Which creates this conversion graph:

+------------+    +-----------------+    +------------------+
| src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
|  [ctf-fs]  |    |     [muxer]     |    |     [pretty]     |
|            |    |                 |    |                  |
|    stream0 @--->@ in0         out @--->@ in               |
|    stream1 @--->@ in1             |    +------------------+
|    stream2 @--->@ in2             |
|    stream3 @--->@ in3             |
+------------+    |                 |
                  |                 |
+------------+    |                 |
| src.ctf.fs |    |                 |
| [ctf-fs-2] |    |                 |
|            |    |                 |
|    stream0 @--->@ in4             |
|    stream1 @--->@ in5             |
+------------+    @ in6             |
                  +-----------------+

And it's equivalent to this babeltrace2-run(1) command line:

$ babeltrace2 run --component=ctf-fs:src.ctf.fs \
                  --params='inputs=["/path/to/trace"] \
                  --component=ctf-fs-2:src.ctf.fs \
                  --params='inputs=["/path/to/other/trace"] \
                  --component=muxer:filter.utils.muxer \
                  --component=pretty:sink.text.pretty \
                  --connect=ctf*:muxer --connect=muxer:pretty

You can use the --run-args option to make the convert command print its equivalent run command arguments instead of creating and running the conversion graph. The printed arguments are escaped for shells, which means you can use them as-is on the command line and possibly add more options to the run command:

$ babeltrace2 run $(babeltrace2 --run-args /path/to/trace) ...

The --run-args-0 option is like the --run-args option, except the printed arguments are NOT escaped and they're separated by a null character instead of a space. Super useful when the resulting arguments aren't the direct input of a shell — for example, if you're passing them to xargs -0. 🧚

See "EXAMPLES" for usage examples.

🎀 Create explicit components 🎀

To explicitly create a component, use the --component option. This option specifies:

  • Optional: The name of the component.
  • The type of the component class to instantiate: source, filter, or sink.
  • The name of the plugin in which to find the component class to instantiate.
  • The name of the component class to instantiate.

You can use the --component option multiple times to create multiple components, and you can instantiate the same component class multiple times as different component instances. Slay. 👑

Immediately following a --component option on the command line, the created component is known as the current component (until the next --component option or non-option argument).

The following command-line options apply to the current component:

  • --log-level=LVL — Set the log level of the current component to LVL.
  • --params=PARAMS — Add PARAMS to the initialization parameters of the current component. If PARAMS contains a key which exists in the initialization parameters of the current component, then replace the parameter.

See "EXAMPLES" for usage examples.

🎀 Create implicit components from non-option arguments 🎀

When you specify a non-option argument to the convert command, it tries to find one or more components which can handle that argument. It's giving matchmaker energy fr fr. 💖

For example, with this command line:

$ babeltrace2 /path/to/trace

If /path/to/trace is a CTF trace directory, then the convert command creates a source.ctf.fs component to handle this specific trace.

This automatic source component discovery mechanism is possible thanks to component classes which support the babeltrace.support-info query object (see babeltrace2-query-babeltrace.support-info(7)).

The non-option argument can also be a directory. If no component can handle that specific directory, then the convert command traverses that directory and recursively tries to find compatible components for each file and subdirectory. Which means a single non-option argument can lead to the creation of many implicit components. The way that one little argument can just spawn a whole squad… 😭

The following command-line options apply to ALL the implicit components created from the last non-option argument:

  • --log-level=LVL — Set the log level of those implicit components to LVL.
  • --params=PARAMS — Add PARAMS to the initialization parameters of those implicit components. For a given implicit component, if PARAMS contains a key which exists in the initialization parameters of this component, then replace the parameter.

Note that it's also possible for two non-option arguments to cause the creation of a single implicit component. For example, if you specify:

$ babeltrace2 /path/to/chunk1 /path/to/chunk2

where /path/to/chunk1 and /path/to/chunk2 are paths to chunks of the same logical CTF trace, then the convert command creates a single source.ctf.fs component which receives both paths at initialization time. When this happens, any --log-level or --params option that you specify to one of them applies to that single implicit component. For example:

$ babeltrace2 /path/to/chunk1 --params=clock-class-offset-s=450 \
              /path/to/chunk2 --params=clock-class-offset-ns=98 \
              --log-level=INFO

Here, the single implicit component gets both the clock-class-offset-s and clock-class-offset-ns initialization parameters, plus the INFO log level. Look at them sharing. 🫶

For backward compatibility with the babeltrace(1) program, the convert command ignores any non-option argument which does not cause the creation of any component. In that case, it emits a warning log statement and continues.

🎀 Create implicit components from options 🎀

There are many ways to create implicit components from options with the convert command:

  • To create an implicit filter.utils.trimmer component (stream trimmer), specify the --begin, --end, or --timerange option.

Examples:

$ babeltrace2 /path/to/trace --begin=22:14:38 --end=22:15:07

$ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07

$ babeltrace2 /path/to/trace --end=12:31:04.882928015
  • to make an implicit filter.lttng-utils.debug-info (that's the one that sprinkles debugging info onto compatible LTTng events, bestie ✨), just pass any of --debug-info, --debug-info-dir, --debug-info-full-path, or --debug-info-target-prefix. Any one of them. It's giving choose-your-own-adventure 💅

Examples, since examples are the moment:

$ babeltrace2 /path/to/trace --debug-info

$ babeltrace2 /path/to/trace \
              --debug-info-target-prefix=/tmp/tgt-root

$ babeltrace2 /path/to/trace --debug-info-full-path
  • to make an implicit sink.text.pretty component (pretty text output going to stdout or to a file, iconic behavior honestly 💖), you specify no other sink components at all, explicit or implicit.

Like, the implicit sink.text.pretty component is just there by default, main character energy. But the second any other explicit or implicit sink component shows up, the convert command stops auto-creating it. Not me gatekeeping pretty output but okay 🫶

The --clock-cycles, --clock-date, --clock-gmt, --clock-seconds, --color, --fields, --names, and --no-delta options all apply to the implicit sink.text.pretty component. Every single one, no cap.

And --output without --output-format=ctf makes the implicit sink.text.pretty component write its content to a file — except the warnings for backward compatibility with the babeltrace(1) program. Yeah. Those stay warning-ing. iykyk.

Examples:

$ babeltrace2 /path/to/trace

$ babeltrace2 /path/to/trace --no-delta

$ babeltrace2 /path/to/trace --output=/tmp/pretty-out
  • to make an implicit sink.utils.dummy component (which produces, and I cannot stress this enough, no output whatsoever 💀), you pass --output-format=dummy.

Example:

$ babeltrace2 /path/to/trace --output-format=dummy
  • to make an implicit sink.ctf.fs component (that's CTF traces written out to the file system, we love a glow-up 🌸), you pass --output-format=ctf and --output=DIR where DIR is the base output directory.

Example:

$ babeltrace2 /path/to/input/trace --output-format=ctf \
              --output=my-traces

Now, as of this version, a sink.ctf.fs component generates CTF 2 traces by default (peep <https://diamon.org/ctf/>). If you're out here wanting CTF 1.8 instead (see <https://diamon.org/ctf/v1.8.3/>), you gotta create an explicit sink.ctf.fs component — scroll down to “Create explicit components” — and use the ctf-version="1" initialization parameter:

$ babeltrace2 /path/to/input/trace --component=sink.ctf.fs \
              --params='path="my-traces",ctf-version="1"'

You can absolutely combine multiple methods to create multiple implicit components at once. Like, the multitasking is real. For example, trim an LTTng (CTF) trace, add debugging information to it, and write it out as another CTF trace, all in one lil line:

$ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \
              --debug-info --output-format=ctf --output=out-dir

The equivalent babeltrace2-run(1) command of this convert command is:

$ babeltrace2 run --component=auto-disc-source-ctf-fs:source.ctf.fs \
                  --params='inputs=["/path/to/input/trace"]' \
                  --component=sink-ctf-fs:sink.ctf.fs \
                  --params='path="out-dir"' \
                  --component=muxer:filter.utils.muxer \
                  --component=trimmer:filter.utils.trimmer \
                  --params='begin="22:14:38"' \
                  --params='end="22:15:07"' \
                  --component=debug-info:filter.lttng-utils.debug-info \
                  --connect=auto-disc-source-ctf-fs:muxer \
                  --connect=muxer:trimmer \
                  --connect=trimmer:debug-info \
                  --connect=debug-info:sink-ctf-fs

The order of the implicit component options documented in this subsection isn’t significant. So don't stress about sequencing, bestie. It doesn't matter 💅

See “EXAMPLES” for more examples. (There are so many more.)

✨ OPTIONS ✨

🎀 General 🎀

You can use those options before the command name. Yep, before. Front-loaded.

See babeltrace2(1) for more details.

  • -d, --debug — Legacy option, bestie: this is equivalent to --log-level=TRACE.
  • -l LVL, --log-level=LVL — Set the log level of all known Babeltrace 2 loggers to LVL.
  • --omit-home-plugin-path — Don’t search for plugins in $HOME/.local/lib/babeltrace2/plugins.
  • --omit-system-plugin-path — Don’t search for plugins in /usr/local/lib/babeltrace2/plugins.
  • --plugin-path=PATH[:PATH]... — Add PATH to the list of paths in which plugins can be found.
  • -v, --verbose — Legacy option: this is equivalent to --log-level=INFO.

🦋 Explicit component creation 🦋

See “Create explicit components” to learn how to use the following option.

  • -c [NAME:]COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME, --component= [NAME:]COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME — Create a component named NAME (if you specified one, that is) from the component class of type COMP-CLS-TYPE named COMP-CLS-NAME found in the plugin named PLUGIN-NAME, and set it as the current component. 💅

The available values for COMP-CLS-TYPE are:

  • source, src — Source component class.
  • filter, flt — Filter component class.
  • sink — Sink component class.

🧚 Common component creation 🧚

See “Create explicit components” and “Create implicit components from non-option arguments” to learn how to use the following options.

These options apply to either the current explicit component (that's the last --component option) or to ALL the implicit components created from the last non-option argument. Both. Yes. It's giving versatile.

  • -l LVL, --log-level=LVL — Set the log level of the current component(s) to LVL.

The available values for LVL are:

  • NONE, N — Logging is disabled. Radio silence 🫥
  • FATAL, F — Severe errors that lead the execution to abort immediately.

This level should be enabled in production.

  • ERROR, E — Errors that might still allow the execution to continue.

Usually, once one or more errors are reported at this level, the application, plugin, or library won’t perform any more useful task, but it should still exit cleanly. (So like, it's done, but it leaves politely.)

This level should be enabled in production.

  • WARN, WARNING, W — Unexpected situations which still allow the execution to continue.

This level should be enabled in production.

  • INFO, I — Informational messages that highlight progress or important states of the application, plugins, or library.

This level can be enabled in production.

  • DEBUG, D — Debugging information, with a higher level of details than the TRACE level.

This level should NOT be enabled in production. Ma'am. Please.

  • TRACE, T — Low-level debugging context information.

This level should NOT be enabled in production. Fr fr.

  • -p PARAMS, --params=PARAMS — Add PARAMS to the initialization parameters of the current component(s).

If PARAMS contains a key which already exists in the initialization parameters of the current component(s), then replace the parameter. Out with the old, in with the new 💅

The format of PARAMS is a comma-separated list of NAME=VALUE assignments:

NAME=VALUE[,NAME=VALUE]...

NAME — Parameter name (C identifier plus the :, ., and - characters).

VALUE — One of:

  • null, nul, NULL: null value.
  • true, TRUE, yes, YES: true boolean value.
  • false, FALSE, no, NO: false boolean value.
  • Binary (0b prefix), octal (0 prefix), decimal, or hexadecimal (0x prefix) unsigned (with + prefix) or signed 64-bit integer.
  • Double precision floating point number (scientific notation is accepted).
  • Unquoted string with no special characters, and not matching any of the null and boolean value symbols above.
  • Double-quoted string (accepts escape characters).
  • Array, formatted as an opening [, a comma-separated list of VALUE, and a closing ].
  • Map, formatted as an opening {, a comma-separated list of NAME=VALUE assignments, and a closing }.

You may put whitespaces around the individual = (assignment), , (separator), [ (array beginning), ] (array end), { (map beginning), and } (map end) characters. Live your life, add the spaces 🌸

Example:

--params='many=null, fresh=yes, condition=false, squirrel=-782329,
          play=+23, observe=3.14, simple=beef,
          needs-quotes="some string",
          escape.chars-are:allowed="a \" quote",
          things=[1, "hello", 2.71828],
          frog={slow=2, bath=[bike, 23], blind=NO}'
Important — Like in the example above, make sure to single-quote the whole argument when you run this command from a shell, because it can contain so many special characters. Protect your lil string, bestie 🫶

🌈 Legacy options to create implicit components 🌈

  • -i FORMAT, --input-format=FORMAT — Force the convert command to create components from a specific component class for non-option arguments (see “Create implicit components from non-option arguments”), or list available remote LTTng tracing sessions.

The available values for FORMAT are:

  • ctf — Use the source.ctf.fs component class.

Each non-option argument of the command line is a CTF trace or CTF trace chunk.

See babeltrace2-source.ctf.fs(7) to learn more about this component class.

  • lttng-live — Depending on the format of the first non-option argument:
    • net[4]://RDHOST[:RDPORT] — List the available remote LTTng tracing sessions for the LTTng relay daemon at the address RDHOST and port RDPORT (5344 if not specified), and then exit. That's it. List and dip 👋
    • net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION — Use the source.ctf.lttng-live component class.

See babeltrace2-source.ctf.lttng-live(7) to learn more about this component class and the URL format.

You can specify at most one --input-format option. One. Uno. Don't push it 💀

  • -o FORMAT, --output-format=FORMAT — Create an implicit sink component with format FORMAT, or print the metadata text of a CTF trace.

The available values for FORMAT are:

  • text — Create an implicit sink.text.pretty component.

See “Implicit sink.text.pretty component”.

See babeltrace2-sink.text.pretty(7) to learn more about this component class.

  • ctf — Create an implicit sink.ctf.fs component. Specify the base output path with the --output option.

As of this version, a sink.ctf.fs component generates CTF 2 traces by default (peep https://diamon.org/ctf/ for the deets). Wanna write CTF 1.8 instead (that's https://diamon.org/ctf/v1.8.3/)? Then you gotta make an explicit sink.ctf.fs component (scroll to “Create explicit components”) and hand it the ctf-version="1" initialization parameter. Periodt. 💅

Go read babeltrace2-sink.ctf.fs(7) to learn more about this component class, bestie. ✨

dummy

Creates an implicit sink.utils.dummy component.

See babeltrace2-sink.utils.dummy(7) to learn more about this component class. 🦋

ctf-metadata

Prints the metadata text of a CTF trace and dips. 🫶

The first non-option argument is the path to the CTF trace.

You can specify at most one --output-format option. Not two. Not three. One. 🙈

Implicit source.ctf.fs component(s)

See babeltrace2-source.ctf.fs(7) to learn more about this component class. 💜

  • --clock-force-correlate — Sets the force-clock-class-origin-unix-epoch initialization parameter of all the implicit source.ctf.fs components to true.

That force-clock-class-origin-unix-epoch parameter makes every clock class it creates have a Unix epoch origin. Super useful when you need the clock classes of multiple traces to be compatible even when they're lowkey not compatible on their own. 💫

  • --clock-offset=SEC — Sets the clock-class-offset-s initialization parameter of all the implicit source.ctf.fs components to SEC.

The clock-class-offset-s parameter adds SEC seconds to the offsets of all the clock classes that the component creates. ⏰

You can combine this option with --clock-offset-ns.

  • --clock-offset-ns=NS — Sets the clock-class-offset-ns initialization parameter of all the implicit source.ctf.fs components to NS.

The clock-class-offset-ns parameter adds NS nanoseconds to the offsets of all the clock classes that the component creates. ✨

You can combine this option with --clock-offset-s.

Implicit filter.utils.trimmer component

If you specify at least one of the following options, boom, you've created an implicit filter.utils.trimmer component. 🎀

See babeltrace2-filter.utils.trimmer(7) to learn more about this component class.

  • --begin=TIME — Sets the begin initialization parameter of the component to TIME.

You cannot use this option with the --timerange option. Pick a lane bestie 😤

The format of TIME is one of:

YYYY-MM-DD HH:II[:SS[.NANO]]
HH:II[:SS[.NANO]]
[-]SEC[.NANO]
  • YYYY — 4-digit year.
  • MM — 2-digit month (January is 01, because we count like normal people 💅).
  • DD — 2-digit day.
  • HH — 2-digit hour (24-hour format).
  • II — 2-digit minute.
  • SS — 2-digit second.
  • NANO — Nanoseconds (up to nine digits).
  • SEC — Seconds since origin.
  • --end=TIME — Sets the end initialization parameter of the component to TIME.

You cannot use this option with the --timerange option.

See the --begin option for the format of TIME. 👀

  • --timerange=BEGIN,END — Equivalent to --begin=BEGIN and --end=END. Two birds, one flag, slay. 🐦

You can also surround the whole argument with [ and ].

Implicit filter.lttng-utils.debug-info component

If you specify at least one of the following options, you create an implicit filter.lttng-utils.debug-info component. Heads up: this component only alters compatible LTTng events. 🧚

See babeltrace2-filter.lttng-utils.debug-info(7) to learn more about this component class.

  • --debug-info — Creates an implicit filter.lttng-utils.debug-info component.

This option is useless if you specify any of the options below. Like, don't even bother. 💀

  • --debug-info-dir=DIR — Sets the debug-info-dir initialization parameter of the component to DIR.

The debug-info-dir parameter tells the component where to go hunting for the debugging information it needs when it's not chilling inside the actual executable files. 🔍

  • --debug-info-full-path — Sets the full-path initialization parameter of the component to true.

When the full-path parameter is true, the component writes the full (absolute) paths to files in its debugging information fields instead of just the short names. No more mystery meat paths. ✨

  • --debug-info-target-prefix=PREFIX — Sets the target-prefix initialization parameter of the component to PREFIX.

The target-prefix parameter is a path to prepend to the paths to executables recorded in the trace. For example, if a trace contains the executable path /usr/bin/ls in its state dump events, and you specify --debug-info-target-prefix=/home/user/boards/xyz/root, then the component opens the /home/user/boards/xyz/root/usr/bin/ls file to find debugging information. Obsessed with a good prefix. 👑

Implicit sink.text.pretty component

If you specify at least one of the following options, then you force the sink component of the convert command to be an implicit sink.text.pretty component.

See babeltrace2-sink.text.pretty(7) to learn more about this component class. 🌸

  • --clock-cycles — Sets the clock-seconds initialization parameter of the component to true.

The clock-cycles parameter makes the component print the event time in clock cycles. ⏱️

Yeah bestie, the original page literally says clock-seconds right there for --clock-cycles. I'm just the messenger, I don't write the docs, I only vibe with them. 😭
  • --clock-date — Sets the clock-date initialization parameter of the component to true.

The clock-date parameter makes the component print the date and the time of events. 📅

  • --clock-gmt — Sets the clock-gmt initialization parameter of the component to true.

The clock-gmt parameter makes the component not apply the local timezone to the printed times. GMT girlies rise 🌍

  • --clock-seconds — Sets the clock-seconds initialization parameter of the component to true.

The clock-seconds parameter makes the component print the event times in seconds since the Unix epoch. ⏳

  • --color=WHEN — Sets the color initialization parameter of the component to WHEN.

The available values for WHEN are:

  • auto — Only emit terminal color codes when the standard output and error streams are connected to a color-capable terminal. She reads the room. 🎀
  • never — Never emit terminal color codes. 🚫🌈
  • always — Always emit terminal color codes. Rainbow mode, no matter what. 🌈

The auto and always values have no effect if the BABELTRACE_TERM_COLOR environment variable is set to NEVER.

  • --fields=FIELD[,FIELD]... — For each FIELD, sets the field-FIELD initialization parameter of the component to true.

For example, --fields=trace,loglevel,emf sets the field-trace, field-loglevel, and field-emf initialization parameters to true. 🫶

The available value for FIELD are:

  • trace
  • trace:hostname
  • trace:domain
  • trace:procname
  • trace:vpid
  • loglevel
  • emf
  • callsite
  • --names=NAME[,NAME]... — For each NAME, sets the name-NAME initialization parameter of the component to true.

For example, --names=payload,scope sets the name-payload and name-scope initialization parameters to true. ✨

The available value for NAME are:

  • payload
  • context
  • scope
  • header
  • --no-delta — Sets the no-delta initialization parameter of the component to true.

When the no-delta parameter is true, the component doesn't print the duration since the last event on the line. Delta who? Never heard of her. 💅

Shared options

  • -w PATH, --output=PATH — With --output-format=ctf-metadata or --input-format=lttng-live (when printing the available remote LTTng tracing sessions), write the text to the file PATH instead of the standard output.

When you specify --output-format=ctf, set the path initialization parameter of the implicit sink.ctf.fs component to PATH.

Without any specified sink component — explicit or implicit — force the sink component of the convert command to be an implicit sink.text.pretty component and set its path initialization parameter to PATH.

See babeltrace2-sink.ctf.fs(7) and babeltrace2-sink.text.pretty(7) to learn more about those component classes. 📚

Equivalent babeltrace2 run arguments

  • --run-args — Prints the equivalent babeltrace2-run(1) arguments instead of creating and running the conversion graph.

The printed arguments are space-separated and individually escaped for safe shell input. So you can copy-paste without fear. 🫶

You cannot use this option with the --run-args-0 or --stream-intersection option.

  • --run-args-0 — Prints the equivalent babeltrace2-run(1) arguments instead of creating and running the conversion graph.

The printed arguments are separated with a null character and NOT escaped for safe shell input. Different vibe, different rules. 💀

You cannot use this option with the --run-args or --stream-intersection option.

Conversion graph configuration

  • -m VERSION, --allowed-mip-versions=VERSION — Only allows the conversion graph to honour version VERSION (0 or 1) of the Message Interchange Protocol (MIP) instead of allowing both versions. Pick one, bestie. 😌
  • --retry-duration=TIME-US — Sets the duration of a single retry to TIME-US µs when a sink component reports “try again later” (busy network or file system, for example). She's patient but not that patient. ⏰

Default: 100000 (100 ms).

  • --stream-intersection — Enables the stream intersection mode. 🔥

In this mode, for each trace, the convert command filters out the events and other messages which aren't in the time range where all the trace streams are active.

To use this option, all the source components, explicit and implicit, must have classes which support the babeltrace.trace-infos query object (see babeltrace2-query-babeltrace.trace-infos(7)). The only component class of the Babeltrace 2 project which supports this query object is source.ctf.fs. That's the whole guest list. 🙈

You cannot use this option with the --run-args or --run-args-0 option.

Other legacy options

The following options exist for backward compatibility with the babeltrace(1) program. Ancient artifacts, but make no mistake, they still hit. 🏺✨

  • -d, --debug — Legacy option: this is equivalent to --log-level=TRACE, where --log-level is the general option (not the --log-level option of this command). Yes, the naming is giving chaos. 💀
  • -v, --verbose — Legacy option: this is equivalent to --log-level=INFO, where --log-level is the general option (not the --log-level option of this command).

This option also sets the verbose parameter of the implicit sink.text.pretty component (see babeltrace2-sink.text.pretty(7)) to true. 🗣️

Command information

  • -h, --help — Shows the command help and quits. Your lil cheat sheet, bestie. 🎀

Example 1. Pretty-print the events, in order, of one or more CTF traces. 👑

No args, no stress — just hand it your trace(s) and it spills every event in order. One trace, the same trace twice, or a whole lil squad of them:

$ babeltrace2 my-ctf-traces

$ babeltrace2 my-ctf-traces

$ babeltrace2 my-ctf-trace-1 my-ctf-trace-2 my-ctf-trace-3

Example 2. Trim a CTF trace and pretty-print the events. ✂️

Give it a --begin, an --end, both, or a --timerange — whatever vibe you're on:

$ babeltrace2 my-ctf-trace --begin=22:55:43.658582931 \
                           --end=22:55:46.967687564

$ babeltrace2 my-trace --begin=22:55:43.658582931

$ babeltrace2 my-trace --end=22:55:46.967687564

$ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564

Example 3. Trim a CTF trace, enable the stream intersection mode, and write a CTF trace. 🔥

Trim it, flip on --stream-intersection, then write the whole thing back out as CTF:

$ babeltrace2 my-ctf-trace --stream-intersection \
              --timerange=22:55:43,22:55:46.967687564 \
              --output-format=ctf --output=out-ctf-trace

Example 4. Print the available remote LTTng sessions (through LTTng live). 📡

Peep which remote sessions are out there:

$ babeltrace2 --input-format=lttng-live net://localhost

Example 5. Pretty-print LTTng live events. 💅

Just point at a live session URL and watch the events roll in:

$ babeltrace2 net://localhost/host/myhostname/my-session-name

Example 6. Record LTTng live traces to the file system (as CTF 1.8 traces). 💾

Save that live stream straight to disk — with session-not-found-action=end so it knows what to do if the session ghosts you, and ctf-version="1" for the CTF 1.8 flavor:

$ babeltrace2 net://localhost/host/myhostname/my-session-name \
              --params=session-not-found-action=end \
              --component=sink.ctf.fs \
              --params='path="out-ctf-traces",ctf-version="1"'

Example 7. Read a CTF trace as fast as possible using a dummy output. ⚡

You don't want output, you want speed. Dummy sink it is:

$ babeltrace2 my-trace --output-format=dummy

Example 8. Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file. 🎀

Three traces, intersected, debug info sprinkled in, and everything lands in pretty-out instead of your terminal:

$ babeltrace2 ctf-trace1 ctf-trace2 ctf-trace3 --stream-intersection \
              --debug-info --output=pretty-out

Example 9. Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since the Unix epoch. 🌈

Mix a plain trace with a hand-picked source component, and show timestamps as seconds-since-epoch with --clock-seconds:

$ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
              --params='path="spec-trace",output-some-event-type=yes' \
              --clock-seconds

Example 10. Send LTTng live events to an explicit sink component. 👑

Live events, but they go wherever you say:

$ babeltrace2 net://localhost/host/myhostname/mysession \
              --component=sink.my-plugin.my-sink

Example 11. Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace. 🧚

Trim + debug info + your own filter component (with its own --params) + CTF output. The full glow-up pipeline:

$ babeltrace2 /path/to/ctf/trace --timerange=22:14:38,22:15:07 \
              --debug-info --component=filter.my-plugin.my-filter \
              --params=criteria=xyz,ignore-abc=yes \
              --output-format=ctf --output=out-ctf-trace

Example 12. Print the metadata text of a CTF trace. 📜

Just the metadata, nothing else:

$ babeltrace2 /path/to/ctf/trace --output-format=ctf-metadata

🌸 ENVIRONMENT VARIABLES 🌸

Babeltrace 2 library

  • BABELTRACE_EXEC_ON_ABORT=CMDLINE — runs the command line CMDLINE, parsed like a UNIX 98 shell, whenever any part of the Babeltrace 2 project unexpectedly aborts. 😭

The application only aborts after that executed command returns — and it straight-up ignores that command's exit status.

This environment variable gets ignored when the application has the setuid or the setgid access right flag set. 🚩
  • BABELTRACE_TERM_COLOR=(AUTO | NEVER | ALWAYS) — forces the terminal color support for the babeltrace2(1) program and the project plugins. 🎨

The available values are:

  • AUTO — only emit terminal color codes when the standard output and error streams are connected to a color-capable terminal.
  • NEVER — never emit terminal color codes.
  • ALWAYS — always emit terminal color codes.
  • BABELTRACE_TERM_COLOR_BRIGHT_MEANS_BOLD=0 — set it to 0 to emit SGR (see https://en.wikipedia.org/wiki/ANSI_escape_code) codes 90 to 97 for bright colors instead of bold (SGR code 1) and standard color codes (SGR codes 30 to 37).
  • BABELTRACE_PLUGIN_PATH=PATHS — sets the list of directories, in order, in which dynamic plugins can be found before other directories are considered, to PATHS (colon-separated, or semicolon on Windows).
  • LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS=1 — disables the loading of any Babeltrace 2 Python plugin. 🐍🚫
  • LIBBABELTRACE2_INIT_LOG_LEVEL=LVL — forces the initial log level of the Babeltrace 2 library to be LVL.

If this environment variable is set, then it overrides the log level set by the --log-level option for the Babeltrace 2 library logger.

The available values for LVL are:

  • NONE, N — logging is disabled.
  • FATAL, F — severe errors that lead the execution to abort immediately. This level should be enabled in production.
  • ERROR, E — errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won't perform any more useful task, but it should still exit cleanly. This level should be enabled in production.
  • WARN, WARNING, W — unexpected situations which still allow the execution to continue. This level should be enabled in production.
  • INFO, I — informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production.
  • DEBUG, D — debugging information, with a higher level of details than the TRACE level. This level should NOT be enabled in production.
  • TRACE, T — low-level debugging context information. This level should NOT be enabled in production.
  • LIBBABELTRACE2_NO_DLCLOSE=1 — makes the Babeltrace 2 library leave any dynamically loaded modules (plugins and plugin providers) open at exit. This can be useful for debugging purposes. 🐛
  • LIBBABELTRACE2_PLUGIN_PROVIDER_DIR=DIR — sets the directory from which the Babeltrace 2 library dynamically loads plugin provider shared objects to DIR.

If this environment variable is set, then it overrides the default plugin provider directory.

Babeltrace 2 Python bindings

  • BABELTRACE_PYTHON_BT2_LOG_LEVEL=LVL — forces the Babeltrace 2 Python bindings log level to be LVL.

If this environment variable is set, then it overrides the log level set by the --log-level option for the Python bindings logger.

The available values for LVL are:

  • NONE, N — logging is disabled.
  • FATAL, F — severe errors that lead the execution to abort immediately. This level should be enabled in production.
  • ERROR, E — errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won't perform any more useful task, but it should still exit cleanly. This level should be enabled in production.
  • WARN, WARNING, W — unexpected situations which still allow the execution to continue. This level should be enabled in production.
  • INFO, I — informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production.
  • DEBUG, D — debugging information, with a higher level of details than the TRACE level. This level should NOT be enabled in production.
  • TRACE, T — low-level debugging context information. This level should NOT be enabled in production.

CLI

  • BABELTRACE_CLI_LOG_LEVEL=LVL — forces the log level of the log level babeltrace2 CLI to be LVL. (Yes, that sentence is doing the most, but that's literally what it says. 💀)

If this environment variable is set, then it overrides the log level set by the --log-level option for the CLI logger.

The available values for LVL are:

  • NONE, N — logging is disabled.
  • FATAL, F — severe errors that lead the execution to abort immediately. This level should be enabled in production.
  • ERROR, E — errors that might still allow the execution to continue. Usually, once one or more errors are reported at this level, the application, plugin, or library won't perform any more useful task, but it should still exit cleanly. This level should be enabled in production.
  • WARN, WARNING, W — unexpected situations which still allow the execution to continue. This level should be enabled in production.
  • INFO, I — informational messages that highlight progress or important states of the application, plugins, or library. This level can be enabled in production.
  • DEBUG, D — debugging information, with a higher level of details than the TRACE level. This level should NOT be enabled in production.
  • TRACE, T — low-level debugging context information. This level should NOT be enabled in production.
  • BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH=0 — disables the warning message which babeltrace2-convert(1) prints when you convert a trace with a relative path that's also the name of a babeltrace2 command.
  • BABELTRACE_DEBUG=1 — legacy variable: equivalent to setting the --log-level option to TRACE. 🕰️
  • BABELTRACE_VERBOSE=1 — legacy variable: equivalent to setting the --log-level option to INFO. 🕰️

🦋 FILES 🦋

  • $HOME/.local/lib/babeltrace2/plugins — user plugin directory.
  • /usr/local/lib/babeltrace2/plugins — system plugin directory.
  • /usr/local/lib/babeltrace2/plugin-providers — system plugin provider directory.

⭐ EXIT STATUS ⭐

0 on success, 1 otherwise. That's it, that's the whole range, no in-between drama. 🎯

💀 BUGS 💀

If you encounter any issue or usability problem, please report it on the Babeltrace bug tracker (see https://bugs.lttng.org/projects/babeltrace). Don't suffer in silence bestie, they wanna know. 🫶

🌈 RESOURCES 🌈

The Babeltrace project shares some communication channels with the LTTng project (see https://lttng.org/).

👑 AUTHORS

Babeltrace 2 is literally the glow-up result of so many people's hard work, bestie — regular devs showing up every day and occasional contributors dropping in with that main character energy. Everyone ate. 💖

The current project maintainer is Jérémie Galarneau <mailto:jeremie.galarneau@efficios.com>. Respect the crown. 🫶

This command is part of the Babeltrace 2 project. Slay.

Babeltrace is distributed under the MIT license (see <https://opensource.org/licenses/MIT>). No cap, that's the whole license vibe. ✨

🦋 SEE ALSO

iykyk — go read the intro one if you're new here, it's giving tutorial energy. 💅

okay bestie that's the whole page, you made it to the end, I'm so proud of you 😭💖

This lil masterpiece is from Babeltrace 2.1.2, dated 13 December 2024, and the manual page is filed under BABELTRACE2-CONVERT(1). Go convert something iconic. 🎀🌈⭐

📦 where this page comes from