-babeltrace2-run(1)
-=================
+= babeltrace2-run(1)
:manpagetype: command
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-run - Create a trace processing graph and run it
+== NAME
+
+babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it
-SYNOPSIS
---------
+[[synopsis]]
+== SYNOPSIS
+
[verse]
-*babeltrace2 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'
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *run* [opt:--retry-duration='TIME-US']
+ opt:--connect='CONN-RULE'... 'COMPONENTS'
+
+== DESCRIPTION
-DESCRIPTION
------------
-The `run` command creates a trace processing graph and runs it.
+The `run` command creates a Babeltrace~2 trace processing graph and
+runs it.
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+include::common-see-babeltrace2-intro.txt[]
-The `run` command uses libbabeltrace2 to dynamically load plugins which
+The `run` command dynamically loads Babeltrace~2 plugins which
supply component classes. With the `run` command, you specify which
-component classes to instantiate as components and how they must be
-connected.
+component classes to instantiate as components and how to connect them.
The steps to write a `babeltrace2 run` command line are:
-. Specify which component classes to instantiate as components and
- how. This is the 'COMPONENTS' part of the synopsis. See
- <<create-comps,Create components>> to learn more.
+. Specify which component classes to instantiate as components with many
+ opt:--component options and how to configure them.
++
+This is the 'COMPONENTS' part of the <<synopsis,synopsis>>. See
+<<create-comps,``Create components''>> to learn more.
-. Specify how to connect component instances together with one or more
- opt:--connect options. See <<connect-comps,Connect components>> to
- learn more.
+. Specify how to connect components together with one or more
+ opt:--connect options.
++
+See <<connect-comps,``Connect components''>> to learn more.
NOTE: The man:babeltrace2-convert(1) command is a specialization of the
`run` command for the very common case of converting one or more traces:
[[create-comps]]
-Create components
-~~~~~~~~~~~~~~~~~
+=== 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 name of the component, unique amongst all the component names of
+ the trace processing graph.
* The type of the component class to instantiate: source, filter, or
sink.
* 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.
+Use the opt:--component option multiple times to create multiple
+components. You can instantiate the same component class multiple times
+as different components.
At any point in the command line, the opt:--base-params sets the current
base initialization parameters and the opt:--reset-base-params resets
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 <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+The opt:--params='PARAMS' option adds parameters to the current
+component's initialization parameters. If 'PARAMS' contains a key which
+exists in the current component's initialization parameters, this
+parameter is replaced.
[[connect-comps]]
-Connect components
-~~~~~~~~~~~~~~~~~~
+=== Connect components
+
The components which you create from component classes with the
-opt:--component option (see <<create-comps,Create components>>) 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.
+opt:--component option (see <<create-comps,``Create components''>>) add
+input and output _ports_ depending on their type. An output port is from
+where messages, like trace events, are sent. An input port is where
+messages are received. For a given component, 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.
+with one or more opt:--connect='CONN-RULE' options.
-The format of a connection rule (the argument of the opt:--connect
-option) is:
+The format of 'CONN-RULE' is:
[verse]
__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
-'UP-COMP-PATH'::
+'UP-COMP-PAT'::
Upstream component name pattern.
'UP-PORT-PAT'::
- Upstream port name pattern.
+ Upstream (output) port name pattern.
-'DOWN-COMP-PATH'::
+'DOWN-COMP-PAT'::
Downstream component name pattern.
'DOWN-PORT-PAT'::
- Downstream port name pattern.
+ Downstream (input) 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:
+For each connection rule (--connect options, in order):
+ 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 trace 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.
+ Select the first input port of COMP of which the name matches
+ DOWN-PORT-PAT, or fail with no match.
+
+No possible connection: fail with no match.
----
__UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
equivalent to `*`.
You can leverage this connection mechanism to specify fallbacks with a
-careful use of wildcards. For example:
+careful use of wildcards, as the order of the opt:--connect options on
+the command line is significant. For example:
----
--connect='A.out*:B.in*' --connect=A:B --connect='*:C'
----
-With those connection rules:
+With those connection rules, the `run` command connects:
* 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`.
+ 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 component `A` 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`.
+* Any other output port (of any component except `A`) 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.
+connect a given output port using the provided connection rules.
-See <<examples,EXAMPLES>> for more examples.
+See <<examples,``EXAMPLES''>> for more examples.
-include::common-cmd-params-format.txt[]
+== OPTIONS
-include::common-cmd-plugin-path.txt[]
+include::common-gen-options.txt[]
-OPTIONS
--------
-include::common-gen-options.txt[]
+=== Component creation
+See <<create-comps,``Create components''>> for more details.
-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 <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+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 the opt:--params option 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.
+opt:-c __NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME'::
+opt:--component=__NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME'::
+ Create a component named 'NAME' 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 'TYPE' are:
+
the current base initialization parameters (see the opt:--base-params
option).
-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:-l 'LVL'::
+opt:--log-level='LVL'::
+ Set the log level of the current component to 'LVL'.
++
+The available values for 'LVL' are:
++
+--
+include::common-log-levels.txt[]
+--
-opt:-p 'PARAMS', opt:--params='PARAMS'::
+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 <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+ component.
++
+If 'PARAMS' contains a key which exists in the current component's
+initialization parameters, replace the parameter.
++
+--
+include::common-cmd-params-format.txt[]
+--
+
+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:-r, opt:--reset-base-params::
- Reset the current base parameters. You can set the current base
- parameters with the opt:--base-params option.
+=== Component connection
+opt:-x 'CONN-RULE'::
+opt:--connect='CONN-RULE'::
+ Add the connection rule 'CONN-RULE'.
++
+The format of 'CONN-RULE' is:
++
+[verse]
+__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
++
+--
+'UP-COMP-PAT'::
+ Upstream component name pattern.
+
+'UP-PORT-PAT'::
+ Upstream (output) port name pattern.
+
+'DOWN-COMP-PAT'::
+ Downstream component name pattern.
+
+'DOWN-PORT-PAT'::
+ Downstream (input) port name pattern.
+--
++
+See <<connect-comps,``Connect components''>> to learn more.
-Component connection
-~~~~~~~~~~~~~~~~~~~~
-opt:-x 'CONN-RULE', opt:--connect='CONN-RULE'::
- Add the connection rule 'CONN-RULE'. See
- <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
+=== Graph configuration
-Graph configuration
-~~~~~~~~~~~~~~~~~~~
-opt:--retry-duration='DURUS'::
- Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+opt:--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{nbsp}ms).
+Default: 100000 (100~ms).
-include::common-plugin-path-options.txt[]
-
include::common-cmd-info-options.txt[]
[[examples]]
-EXAMPLES
---------
+== EXAMPLES
+
.Create a single-port source component and a single-port sink component and connect them.
====
[role="term"]
----
$ babeltrace2 run --component=A:src.plug.my-src \
- --component=B:sink.plug.my-sink \
- --connect=A:B
+ --component=B:sink.plug.my-sink \
+ --connect=A:B
----
Possible resulting graph:
----
====
-.Use the opt:--name option to name the current component.
-====
-[role="term"]
-----
-$ babeltrace2 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
[role="term"]
----
$ babeltrace2 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
+ --params=offset=123,flag=true \
+ --component=the-sink:sink.my-plugin.my-sink \
+ --connect=the-source:the-sink
----
====
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`
+Component `A`::
+ `offset=1203, flag=false`
+
+Component `B`::
+ `offset=1203, flag=true, type=event`
+
+Component `C`::
+ `ratio=0.25`
[role="term"]
----
-$ babeltrace2 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
+$ babeltrace2 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
----
====
[role="term"]
----
$ babeltrace2 run --component=A:src.plug.my-src \
- --component=B:sink.plug.my-sink \
- --connect='A.foo*:B:nin*' --connect='A:B.oth*'
+ --component=B:sink.plug.my-sink \
+ --connect='A.foo*:B:nin*' --connect='A:B.oth*'
----
Possible resulting graph:
include::common-cli-env.txt[]
+
include::common-cli-files.txt[]
+
include::common-cmd-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
+man:babeltrace2-intro(7),
man:babeltrace2(1),
-man:babeltrace2-convert(1),
-man:babeltrace2-intro(7)
+man:babeltrace2-convert(1)
projects / babeltrace.git / blobdiff