CLI: add `run` command and make `convert` command use it
This patch adds the babeltrace(1) command `run` which is essentially the
same as the current `convert` command without the magic stuff (legacy
options and their interesting constraints), plus this:
* You can set the name of a component by prefixing the --source,
--filter, or --sink option's argument with `NAME:`. You can escape
`.`, `:`, and `\` with `\`. Example:
--source=instance:ctf.fs --sink=my-text:text.text
--filter='my\.name:my\.plugin.my\.comp\.cls'
This is the equivalent of:
--source=ctf.fs --name=instance --sink=text.text --name=my-text
--filter='my\.plugin.my\.comp\.cls' --name my.name
The --name option still exists: it sets the current name of the
current component, so that, with this:
--sink=a:b.c --name=salut --name=bonjour
the effective name of this component is `bonjour`.
* You can use the new --key and --value options to add one string
initialization parameter to the current component. The name of this
parameter is given by the last --key option's argument, and its value
by the --value option's argument. Examples:
--source=ctf.fs --key=path --value ~/lttng-traces/...
--key=path --source=ctf.fs --value ~/lttng-traces/...
This is useful to not care about the specific escaping required by the
--params option format for a string parameter, to use any parameter
name, and to use shell expansion for the value (tilde expansion for
example, as --path is not a `run` command's option).
The `convert` command is now a specialization of the `run` command,
specific to a _conversion graph_ (whereas the terminology for what you
build with the `run` command is a _processing graph_). The conversion
graph that the `convert` command builds always has the following
topology:
sources -> utils.muxer -> [utils.trimmer] -> lttng-utils.debug-info -.
.-------------------------------------------------------------'
'-> [user filters] -> sinks
There's no more --connect option in the `convert` command. When you run
the `convert` command, it prepares the equivalent `run` command
arguments and invokes the latter directly. However if `-o ctf-metadata`
exists, a new "print CTF metadata" command configuration is created, and
if `-o lttng-live` exists with a URL missing a session name, a new
"print LTTng-live sessions" command configuration is created.
New `convert` options are:
--color=(always | auto | never)
Adds the `color` initialization parameter set to the corresponding
value to the implicit text.text sink component.
--no-debug-info
Do not add an implicit lttng-utils.debug-info filter component to
the filter chain. The lttng-utils.debug-info filter always exists
otherwise.
--run-args
Instead of invoking the `run` command, prints to the standard output
the equivalent `run` command arguments, formatted for a shell. This
means you can copy the whole output and use it as is to execute
`babeltrace run` without escaping, so that the two following
commands are equivalent:
babeltrace convert [...]
babeltrace run $(babeltrace convert --run-args [...])
You can also use this trick to augment the conversion graph with the
`run` command, for example:
babeltrace run --base-params common-to-each-convert-comp=23
$(babeltrace convert --run-args /path/to/trace
--source=src:my.source [...])
--reset-base-params
--sink=special-sink:my.sink
--connect=src.some-port:special-sink
--run-args-0
Like --run-args, but does not escape the individual arguments for a
shell, and uses the null character as the argument delimiter. This
is useful to get the list of equivalent raw arguments outside a
shell (in a user program), or to use `xargs -0`.
--url=URL
Set the `url` initialization parameter of the current user component
to URL.
Lost `convert` options are:
* --base-params
* --connect
* --reset-base-params
Note that --clock-force-correlate sets the boolean `force-correlate`
initialization parameter of the implicit utils.muxer filter to true.
The necessary conditions to instantiate implicit components are now:
* Implicit ctf.fs source: any of:
* Leftover argument and no --input-format
* Leftover argument and --input-format=ctf
* Leftover argument and --clock-offset
* Leftover argument and --clock-offset-ns
* Leftover argument and --stream-intersection
* Implicit ctf.lttng-live source: any of:
* Leftover argument and --input-format=lttng-live
* Implicit utils.muxer filter: always exists
* Implicit utils.trimmer filter: any of:
* --begin
* --end
* --timerange
* Implicit lttng-utils.debug-info filter:
* No --no-debug-info
* Implicit utils.dummy sink:
* --output-format=dummy
* Implicit text.text sink: any of:
* No --output-format and no --sink
* --output-format=text
* --clock-cycles
* --clock-date
* --clock-gmt
* --clock-seconds
* --color
* --fields
* --names
* --no-delta
* --output
The default names of the implicit components, given by the `convert`
command, to be used by the `run` command, are:
* Implicit ctf.fs source: `ctf`
* Implicit ctf.lttng-live source: `lttng-live`
* Implicit utils.muxer filter: always exists `mux`
* Implicit utils.trimmer filter: `trim`
* Implicit lttng-utils.debug-info filter: `debug-info`
* Implicit utils.dummy sink: `dummy`
* Implicit text.text sink: `text`
If any name is already taken by an explicit user component (--source,
--filter, and --sink), the rule is to try `NAME-0`, then `NAME-1`, then
`NAME-2`, etc. The same rule applies to unnamed user components.
Implicit components are always automatically named after automatically
naming the unnamed user components.
This patch also adds the following:
* Connection cycle detection in babeltrace-cfg-connect.c.
* bt_common_string_until() which returns a substring from a given point
to one of a set of terminating characters, possibly with escapable
characters.
* bt_common_shell_quote() which quotes a string (if necessary) for a
shell.
* bt_common_string_is_printable() which checks if a string contains
only printable characters, including whitespaces.
* bt_common_parse_lttng_live_url() to parse a LTTng-live URL. This is
needed in both the LTTng-live plugin itself and babeltrace-cfg.c to
know if the command is a `run` command or a "print LTTng-live
sessions" command.
* The --name, --source, --filter, --sink, and --connect arguments are
checked with bt_common_string_is_printable().
Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
This page took 0.032471 seconds and 4 git commands to generate.