babeltrace-run(1) ================= :manpagetype: command :revdate: 5 October 2017 NAME ---- babeltrace-run - Create a trace processing graph and run it SYNOPSIS -------- [verse] *babeltrace run* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path] [opt:--omit-system-plugin-path] [opt:--plugin-path='PATH'[:__PATH__]...] [opt:--retry-duration='DURUS'] opt:--connect='CONN-RULE'... 'COMPONENTS' DESCRIPTION ----------- The `run` command creates a trace processing graph and runs it. See man:babeltrace-intro(7) to learn more about the Babeltrace project and its core concepts. The `run` command uses libbabeltrace to dynamically load plugins which supply component classes. With the `run` command, you specify which component classes to instantiate as components and how they must be connected. The steps to write a `babeltrace run` command line are: . Specify which component classes to instantiate as components and how. This is the 'COMPONENTS' part of the synopsis. See <> to learn more. . Specify how to connect component instances together with one or more opt:--connect options. See <> to learn more. NOTE: The man:babeltrace-convert(1) command is a specialization of the `run` command for the very common case of converting one or more traces: it generates a `run` command line and executes it. You can use its manopt:babeltrace-convert(1):--run-args or manopt:babeltrace-convert(1):--run-args-0 option to make it print the equivalent `run` command line instead. [[create-comps]] Create components ~~~~~~~~~~~~~~~~~ To create a component, use the opt:--component option. This option specifies: * **Optional**: The name of the component instance. You can also use the opt:--name option for this. * 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 opt:--component option multiple times to create multiple components. You can instantiate the same component class multiple times as different component instances. At any point in the command line, the opt:--base-params sets the current base initialization parameters and the opt:--reset-base-params resets them. When you specify a opt:--component option, its initial initialization parameters are a copy of the current base initialization parameters. Immediately following a opt:--component option on the command line, the created component is known as the _current component_ (until the next opt:--component option). The following, optional command-line options apply to the current component: opt:--name='NAME':: Set the name of the current component to 'NAME'. opt:--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, this parameter is replaced. + See <> for the format of 'PARAMS'. opt:--key='KEY' followed with opt:--value='VALUE':: Set the current component's initialization parameter named 'KEY' to the string value 'VALUE'. If 'KEY' exists in the current component's initialization parameters, the parameter is replaced. [[connect-comps]] Connect components ~~~~~~~~~~~~~~~~~~ The components which you create from component classes with the opt:--component option (see <>) can create input and output _ports_ depending on their type. An output port is where notifications, like trace events, are sent. An input port is where notifications are received. For a given component instance, each port has a unique name. The purpose of the `run` command is to create a trace processing graph, that is, to know which component ports to connect together. The command achieves this with the help of the connection rules that you provide with the opt:--connect option. The format of a connection rule (the argument of the opt:--connect option) is: [verse] __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] 'UP-COMP-PATH':: Upstream component name pattern. 'UP-PORT-PAT':: Upstream port name pattern. 'DOWN-COMP-PATH':: Downstream component name pattern. 'DOWN-PORT-PAT':: Downstream port name pattern. When a source or filter component adds a new output port within the processing graph, the `run` command does the following to find an input port to connect it to: ---- For each connection rule: If the output port's component's name matches UP-COMP-PAT and the output port's name matches UP-PORT-PAT: For each component COMP in the processing graph: If the name of COMP matches DOWN-COMP-PAT: Select the first input port of COMP of which the name matches DOWN-PORT-PAT, or fail with no match. Fail with no match. ---- __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and __DOWN-PORT-PAT__ are globbing patterns where only the wildcard character, `*`, is special: it matches zero or more characters. You must escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:. When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are equivalent to `*`. You can leverage this connection mechanism to specify fallbacks with a careful use of wildcards. For example: ---- --connect='A.out*:B.in*' --connect=A:B --connect='*:C' ---- With those connection rules: * Any output port of which the name starts with `out` of component `A` is connected to the first input port of which the name starts with `in` of component `B`. * Any other output port of component `A` is connected to the first available input port of component `B`. * Any other output port (of any component except `A`) is connected to the first available input port of component `C`. The `run` command fails when it cannot find an input port to which to connect a created output port using the provided connection rules. See <> for more examples. include::common-cmd-params-format.txt[] include::common-cmd-plugin-path.txt[] OPTIONS ------- include::common-gen-options.txt[] Component creation ~~~~~~~~~~~~~~~~~~ opt:-b 'PARAMS', opt:--base-params='PARAMS':: Set the current base parameters to 'PARAMS'. You can reset the current base parameters with the opt:--reset-base-params option. See <> for the format of 'PARAMS'. opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS':: Create a component initially named 'NAME' (if specified) from the component class of type 'TYPE' named 'COMPCLS' found in the plugin named 'PLUGIN', and set it as the current component. + The available values for 'TYPE' are: + -- `source`:: `src`:: Source component class. `filter`:: `flt`:: Filter component class. `sink`:: Sink component class. -- + The initial initialization parameters of this component are copied from the current base initialization parameters (see the opt:--base-params option). opt:--key='KEY':: Set the current parameter key to 'KEY'. The next opt:--value option uses this key to add a parameter to the current component. opt:--name='NAME':: Set the name of the current component to 'NAME'. The names of all the components in the processing graph must be unique. opt:-p 'PARAMS', opt:--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 <> for the format of 'PARAMS'. opt:-r, opt:--reset-base-params:: Reset the current base parameters. You can set the current base parameters with the opt:--base-params option. opt:-v 'VALUE', opt:--value='VALUE':: Add a parameter to the current component's initialization parameters of which the key is the argument of the last opt:--key option and the string value is 'VALUE'. If the current component's initialization parameters already contain a key named 'KEY', replace the parameter. Component connection ~~~~~~~~~~~~~~~~~~~~ opt:-C 'CONN-RULE', opt:--connect='CONN-RULE':: Add the connection rule 'CONN-RULE'. See <> for the format of 'CONN-RULE'. Graph configuration ~~~~~~~~~~~~~~~~~~~ opt:--retry-duration='DURUS':: Set the duration of a single retry to 'DURUS'{nbsp}µs when a component reports "try again later" (busy network or file system, for example). + Default: 100000 (100{nbsp}ms). include::common-plugin-path-options.txt[] include::common-cmd-info-options.txt[] [[examples]] EXAMPLES -------- .Create a single-port source component and a single-port sink component and connect them. ==== [role="term"] ---- $ babeltrace run --component=A:src.plug.my-src \ --component=B:sink.plug.my-sink \ --connect=A:B ---- Possible resulting graph: ---- +-----------------+ +-------------------+ | src.plug.my-src | | sink.plug.my-sink | | [A] | | [B] | | | | | | out @--->@ in | +-----------------+ +-------------------+ ---- ==== .Use the opt:--name option to name the current component. ==== [role="term"] ---- $ babeltrace run --component=src.plug.my-src --name=the-source \ --component=the-sink:sink.plug.my-sink \ --connect=the-source:the-sink ---- ==== .Use the opt:--params option to set the current component's initialization parameters. ==== In this example, the opt:--params option only applies to component `the-source`. [role="term"] ---- $ babeltrace run --component=the-source:src.my-plugin.my-src \ --params='offset=123, flag=true' \ --component=the-sink:sink.my-plugin.my-sink \ --connect=the-source:the-sink ---- ==== .Use the opt:--key and opt:--value options to set a current component's initialization parameter. ==== [role="term"] ---- $ babeltrace run --component=the-source:src.my-plugin.my-src \ --key=path --value ~/my-traces/the-trace --component=the-sink:sink.my-plugin.my-sink \ --connect=the-source:the-sink ---- ==== .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters. ==== In this example, the effective initialization parameters of the created components are: * Component `A`: `offset=1203, flag=false` * Component `B`: `offset=1203, flag=true, type=event` * Component `C`: `ratio=0.25` [role="term"] ---- $ babeltrace run --base-params='offset=1203, flag=false' \ --component=A:src.plugin.compcls \ --component=B:flt.plugin.compcls \ --params='flag=true, type=event' \ --reset-base-params \ --component=C:sink.plugin.compcls \ --params='ratio=0.25' \ --connect=A:B --connect=B:C ---- ==== .Specify a component connection fallback rule. ==== In this example, any `A` output port of which the name starts with `foo` is connected to a `B` input port of which the name starts with `nin`. Any other `A` output port is connected to a `B` input port of which the name starts with `oth`. The order of the opt:--connect options is important here: the opposite order would create a system in which the first rule is always satisfied, and _any_ `A` output port, whatever its name, would be connected to a `B` input port with a name that starts with `oth`. [role="term"] ---- $ babeltrace run --component=A:src.plug.my-src \ --component=B:sink.plug.my-sink \ --connect='A.foo*:B:nin*' --connect='A:B.oth*' ---- Possible resulting graph: ---- +-----------------+ +-------------------+ | src.plug.my-src | | sink.plug.my-sink | | [A] | | [B] | | | | | | foot @--->@ nine | | foodies @--->@ ninja | | some-port @--->@ othello | | hello @--->@ other | +-----------------+ +-------------------+ ---- ==== include::common-cli-env.txt[] include::common-cli-files.txt[] include::common-cmd-footer.txt[] SEE ALSO -------- man:babeltrace(1), man:babeltrace-convert(1), man:babeltrace-intro(7)