3 :revdate: 14 September 2019
8 babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it
15 *babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *run* [opt:--retry-duration='TIME-US']
16 opt:--connect='CONN-RULE'... 'COMPONENTS'
21 The `run` command creates a Babeltrace~2 trace processing graph and
24 include::common-see-babeltrace2-intro.txt[]
26 The `run` command dynamically loads Babeltrace~2 plugins which
27 supply component classes. With the `run` command, you specify which
28 component classes to instantiate as components and how to connect them.
30 The steps to write a `babeltrace2 run` command line are:
32 . Specify which component classes to instantiate as components with many
33 opt:--component options and how to configure them.
35 This is the 'COMPONENTS' part of the <<synopsis,synopsis>>. See
36 <<create-comps,``Create components''>> to learn more.
38 . Specify how to connect components together with one or more
39 opt:--connect options.
41 See <<connect-comps,``Connect components''>> to learn more.
43 NOTE: The man:babeltrace2-convert(1) command is a specialization of the
44 `run` command for the very common case of converting one or more traces:
45 it generates a `run` command line and executes it. You can use its
46 manopt:babeltrace2-convert(1):--run-args or
47 manopt:babeltrace2-convert(1):--run-args-0 option to make it print the
48 equivalent `run` command line instead.
54 To create a component, use the opt:--component option. This option
57 * The name of the component, unique amongst all the component names of
58 the trace processing graph.
60 * The type of the component class to instantiate: source, filter, or
63 * The name of the plugin in which to find the component class to
66 * The name of the component class to instantiate.
68 Use the opt:--component option multiple times to create multiple
69 components. You can instantiate the same component class multiple times
70 as different components.
72 At any point in the command line, the opt:--base-params sets the current
73 base initialization parameters and the opt:--reset-base-params resets
74 them. When you specify a opt:--component option, its initial
75 initialization parameters are a copy of the current base initialization
78 Immediately following a opt:--component option on the command line, the
79 created component is known as the _current component_ (until the next
80 opt:--component option).
82 The opt:--params='PARAMS' option adds parameters to the current
83 component's initialization parameters. If 'PARAMS' contains a key which
84 exists in the current component's initialization parameters, this
85 parameter is replaced.
89 === Connect components
91 The components which you create from component classes with the
92 opt:--component option (see <<create-comps,``Create components''>>) add
93 input and output _ports_ depending on their type. An output port is from
94 where messages, like trace events, are sent. An input port is where
95 messages are received. For a given component, each port has a unique
98 The purpose of the `run` command is to create a trace processing graph,
99 that is, to know which component ports to connect together. The command
100 achieves this with the help of the connection rules that you provide
101 with one or more opt:--connect='CONN-RULE' options.
103 The format of 'CONN-RULE' is:
106 __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
109 Upstream component name pattern.
112 Upstream (output) port name pattern.
115 Downstream component name pattern.
118 Downstream (input) port name pattern.
120 When a source or filter component adds a new output port within the
121 processing graph, the `run` command does the following to find an
122 input port to connect it to:
125 For each connection rule (--connect options, in order):
126 If the output port's component's name matches UP-COMP-PAT and the
127 output port's name matches UP-PORT-PAT:
128 For each component COMP in the trace processing graph:
129 If the name of COMP matches DOWN-COMP-PAT:
130 Select the first input port of COMP of which the name matches
131 DOWN-PORT-PAT, or fail with no match.
133 No possible connection: fail with no match.
136 __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
137 __DOWN-PORT-PAT__ are globbing patterns where only the wildcard
138 character, `*`, is special: it matches zero or more characters. You must
139 escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:.
141 When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are
144 You can leverage this connection mechanism to specify fallbacks with a
145 careful use of wildcards, as the order of the opt:--connect options on
146 the command line is significant. For example:
149 --connect='A.out*:B.in*' --connect=A:B --connect='*:C'
152 With those connection rules, the `run` command connects:
154 * Any output port of which the name starts with `out` of component `A`
155 to the first input port of which the name starts with `in` of
158 * Any other output port of component `A` to the first available input
159 port of component `B`.
161 * Any other output port (of any component except `A`) to the first
162 available input port of component `C`.
164 The `run` command fails when it cannot find an input port to which to
165 connect a given output port using the provided connection rules.
167 See <<examples,``EXAMPLES''>> for more examples.
172 include::common-gen-options.txt[]
175 === Component creation
177 See <<create-comps,``Create components''>> for more details.
180 opt:--base-params='PARAMS'::
181 Set the current base parameters to 'PARAMS'.
183 You can reset the current base parameters with the
184 opt:--reset-base-params option.
186 See the opt:--params option for the format of 'PARAMS'.
188 opt:-c __NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME'::
189 opt:--component=__NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME'::
190 Create a component named 'NAME' from the component class of type
191 'COMP-CLS-TYPE' named 'COMP-CLS-NAME' found in the plugin named
192 'PLUGIN-NAME', and set it as the current component.
194 The available values for 'TYPE' are:
199 Source component class.
203 Filter component class.
206 Sink component class.
209 The initial initialization parameters of this component are copied from
210 the current base initialization parameters (see the opt:--base-params
214 opt:--log-level='LVL'::
215 Set the log level of the current component to 'LVL'.
217 The available values for 'LVL' are:
220 include::common-log-levels.txt[]
224 opt:--params='PARAMS'::
225 Add 'PARAMS' to the initialization parameters of the current
228 If 'PARAMS' contains a key which exists in the current component's
229 initialization parameters, replace the parameter.
232 include::common-cmd-params-format.txt[]
236 opt:--reset-base-params::
237 Reset the current base parameters.
239 You can set the current base parameters with the opt:--base-params
243 === Component connection
246 opt:--connect='CONN-RULE'::
247 Add the connection rule 'CONN-RULE'.
249 The format of 'CONN-RULE' is:
252 __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
256 Upstream component name pattern.
259 Upstream (output) port name pattern.
262 Downstream component name pattern.
265 Downstream (input) port name pattern.
268 See <<connect-comps,``Connect components''>> to learn more.
271 === Graph configuration
273 opt:--retry-duration='TIME-US'::
274 Set the duration of a single retry to 'TIME-US'~µs when a sink
275 component reports "try again later" (busy network or file system,
278 Default: 100000 (100~ms).
281 include::common-cmd-info-options.txt[]
287 .Create a single-port source component and a single-port sink component and connect them.
291 $ babeltrace2 run --component=A:src.plug.my-src \
292 --component=B:sink.plug.my-sink \
296 Possible resulting graph:
299 +-----------------+ +-------------------+
300 | src.plug.my-src | | sink.plug.my-sink |
304 +-----------------+ +-------------------+
308 .Use the opt:--params option to set the current component's initialization parameters.
310 In this example, the opt:--params option only applies to component
315 $ babeltrace2 run --component=the-source:src.my-plugin.my-src \
316 --params=offset=123,flag=true \
317 --component=the-sink:sink.my-plugin.my-sink \
318 --connect=the-source:the-sink
322 .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters.
324 In this example, the effective initialization parameters of the
325 created components are:
328 `offset=1203, flag=false`
331 `offset=1203, flag=true, type=event`
338 $ babeltrace2 run --base-params=offset=1203,flag=false \
339 --component=A:src.plugin.compcls \
340 --component=B:flt.plugin.compcls \
341 --params=flag=true,type=event \
342 --reset-base-params \
343 --component=C:sink.plugin.compcls \
344 --params=ratio=0.25 \
345 --connect=A:B --connect=B:C
349 .Specify a component connection fallback rule.
351 In this example, any `A` output port of which the name starts with
352 `foo` is connected to a `B` input port of which the name starts with
353 `nin`. Any other `A` output port is connected to a `B` input port of
354 which the name starts with `oth`.
356 The order of the opt:--connect options is important here: the opposite
357 order would create a system in which the first rule is always satisfied,
358 and _any_ `A` output port, whatever its name, would be connected to a
359 `B` input port with a name that starts with `oth`.
363 $ babeltrace2 run --component=A:src.plug.my-src \
364 --component=B:sink.plug.my-sink \
365 --connect='A.foo*:B:nin*' --connect='A:B.oth*'
368 Possible resulting graph:
371 +-----------------+ +-------------------+
372 | src.plug.my-src | | sink.plug.my-sink |
376 | foodies @--->@ ninja |
377 | some-port @--->@ othello |
378 | hello @--->@ other |
379 +-----------------+ +-------------------+
384 include::common-cli-env.txt[]
387 include::common-cli-files.txt[]
390 include::common-cmd-footer.txt[]
395 man:babeltrace2-intro(7),
397 man:babeltrace2-convert(1)