General
You can use those options before the command name.
See babeltrace2(1) for more details.
-d, --debug
Legacy option: 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
Do not search for plugins in
$HOME/.local/lib/babeltrace2/plugins.
--omit-system-plugin-path
Do not 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 specified) 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.
The following options apply to either the current explicit
component (last --component option) or to ALL the implicit
components created from the last non-option argument.
-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.
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.
-p PARAMS, --params=PARAMS
Add PARAMS to the initialization parameters of the current
component(s).
If PARAMS contains a key which exists in the initialization
parameters of the current component(s), replace the
parameter.
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.
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, as
it can contain many special characters.
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.
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.
-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.
See babeltrace2-sink.ctf.fs(7) to learn more about this
component class.
dummy
Create an implicit sink.utils.dummy component.
See babeltrace2-sink.utils.dummy(7) to learn more about
this component class.
ctf-metadata
Print the metadata text of a CTF trace and exit.
The first non-option argument specifies the path to the
CTF trace.
You can specify at most one --output-format option.
Implicit source.ctf.fs component(s)
See babeltrace2-source.ctf.fs(7) to learn more about this
component class.
--clock-force-correlate
Set the force-clock-class-origin-unix-epoch initialization
parameter of all the implicit source.ctf.fs components to
true.
The force-clock-class-origin-unix-epoch initialization
parameter makes all the created clock classes have a Unix
epoch origin. This is useful to force the clock classes of
multiple traces to be compatible even if they are not
inherently.
--clock-offset=SEC
Set the clock-class-offset-s initialization parameter of all
the implicit source.ctf.fs components to SEC.
The clock-class-offset-s initialization 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
Set the clock-class-offset-ns initialization parameter of all
the implicit source.ctf.fs components to NS.
The clock-class-offset-ns initialization 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, you create
an implicit filter.utils.trimmer component.
See babeltrace2-filter.utils.trimmer(7) to learn more about this
component class.
--begin=TIME
Set the begin initialization parameter of the component to
TIME.
You cannot use this option with the --timerange option.
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).
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
Set 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.
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. This
component only alters compatible LTTng events.
See babeltrace2-filter.lttng-utils.debug-info(7) to learn more
about this component class.
--debug-info
Create an implicit filter.lttng-utils.debug-info component.
This option is useless if you specify any of the options
below.
--debug-info-dir=DIR
Set the debug-info-dir initialization parameter of the
component to DIR.
The debug-info-dir parameter indicates where the component
should find the debugging information it needs if it's not
found in the actual executable files.
--debug-info-full-path
Set 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.
--debug-info-target-prefix=PREFIX
Set 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.
Implicit sink.text.pretty component
If you specify at least one of the following options, you force
the convert command's sink component to be an implicit
sink.text.pretty component.
See babeltrace2-sink.text.pretty(7) to learn more about this
component class.
--clock-cycles
Set the clock-seconds initialization parameter of the
component to true.
The clock-cycles parameter makes the component print the
event time in clock cycles.
--clock-date
Set 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
Set 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.
--clock-seconds
Set 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
Set 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.
never
Never emit terminal color codes.
always
Always emit terminal color codes.
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, set 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, set 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
Set the no-delta initialization parameter of the component to
true.
When the no-delta parameter is true, the component does not
print the duration since the last event on the line.
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 convert command's sink component 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
Print 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.
You cannot use this option with the --run-args-0 or --stream-
intersection option.
--run-args-0
Print 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.
You cannot use this option with the --run-args or --stream-
intersection option.
Conversion graph configuration
--retry-duration=TIME-US
Set 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).
Default: 100000 (100 ms).
--stream-intersection
Enable the stream intersection mode.
In this mode, for each trace, the convert command filters out
the events and other messages which are not in the time range
where all the trace's 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
Babeltrace 2 project's component class which supports this
query object is source.ctf.fs.
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.
-d, --debug
Legacy option: this is equivalent to --log-level=TRACE, where
--log-level is the general option (not this command's --log-
level option).
-v, --verbose
Legacy option: this is equivalent to --log-level=INFO, where
--log-level is the general option (not this command's --log-
level option).
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
Show the command's help and quit.
