The convert command converts one or more traces to a given
format, possibly with filters in the conversion path.
See babeltrace2-intro(7) to learn more about the Babeltrace 2
project and its core concepts.
Note
convert is the default babeltrace2(1) command: you generally
don't need to specify its name. The following commands are
equivalent if the ... part does not start with another
babeltrace2(1) command's name, like run or list-plugins:
$ babeltrace2 convert ...
$ babeltrace2 ...
If you need to make sure that you are executing the convert
command, use babeltrace2 convert explicitly.
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. A conversion graph is a linear chain of
components once the source streams are merged:
+----------+
| source 1 @-.
+----------+ |
| +-------+
+----------+ '->@ | +---------+ +------------+
| source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-.
+----------+ .->@ | +---------+ +------------+ |
| +-------+ |
+----------+ | .----------------------------------------'
| ... @-' | +---------------+ +------+
+----------+ '->@ other filters |--->@ sink |
+---------------+ +------+
Note that the trimmer, debugging information, and other filters
are optional. See 'Create implicit components from options' to
learn how to enable them.
If you need another trace processing graph layout, use the more
flexible babeltrace2-run(1) command.
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: this is why the convert command
exists, as 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 path as
non-option arguments to pretty-print the merged events to the
standard output:
$ babeltrace2 /path/to/trace /path/to/other/trace
This 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.
This creates the following 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 |
+-----------------+
It is equivalent to the following 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, but the
printed arguments are NOT escaped and they are separated by a
null character instead of a space. This is useful if the
resulting arguments are not the direct input of a shell, for
example if passed 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. You can instantiate the same component class
multiple times as different component instances.
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 current
component's initialization parameters, 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 this
argument.
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 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. This means that a
single non-option argument can lead to the creation of many
implicit components.
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 this component's initialization parameters,
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 the
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 clock-class-offset-
s and clock-class-offset-ns initialization parameters, as well as
the INFO log level.
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 create an implicit filter.lttng-utils.debug-info (add
debugging information to compatible LTTng events), specify
any of the --debug-info, --debug-info-dir, --debug-info-full-
path, or --debug-info-target-prefix options.
Examples:
$ 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 create an implicit sink.text.pretty component
(pretty-printing text output to the standard output or to a
file), specify no other sink components, explicit or
implicit.
The implicit sink.text.pretty component exists by default. If
any other explicit or implicit sink component exists, the
convert command does not automatically create the implicit
sink.text.pretty component.
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.
The --output option 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.
Examples:
$ babeltrace2 /path/to/trace
$ babeltrace2 /path/to/trace --no-delta
$ babeltrace2 /path/to/trace --output=/tmp/pretty-out
• To create an implicit sink.utils.dummy component (no output),
specify the --output-format=dummy option.
Example:
$ babeltrace2 /path/to/trace --output-format=dummy
• To create an implicit sink.ctf.fs component (CTF traces
written to the file system), specify the --output-format=ctf
and the --output=DIR (base output directory) options.
Example:
$ babeltrace2 /path/to/input/trace --output-format=ctf \
--output=my-traces
You can combine multiple methods to create multiple implicit
components. For example, you can trim an LTTng (CTF) trace, add
debugging information to it, and write it as another CTF trace:
$ 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 is not significant.
See 'EXAMPLES' for more examples.
