4 :revdate: 5 October 2017
9 babeltrace-run - Create a trace processing graph and run it
15 *babeltrace run* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
16 [opt:--omit-system-plugin-path]
17 [opt:--plugin-path='PATH'[:__PATH__]...]
18 [opt:--retry-duration='DURUS']
19 opt:--connect='CONN-RULE'... 'COMPONENTS'
24 The `run` command creates a trace processing graph and runs it.
26 See man:babeltrace-intro(7) to learn more about the Babeltrace
27 project and its core concepts.
29 The `run` command uses libbabeltrace to dynamically load plugins which
30 supply component classes. With the `run` command, you specify which
31 component classes to instantiate as components and how they must be
34 The steps to write a `babeltrace run` command line are:
36 . Specify which component classes to instantiate as components and
37 how. This is the 'COMPONENTS' part of the synopsis. See
38 <<create-comps,Create components>> to learn more.
40 . Specify how to connect component instances together with one or more
41 opt:--connect options. See <<connect-comps,Connect components>> to
44 NOTE: The man:babeltrace-convert(1) command is a specialization of the
45 `run` command for the very common case of converting one or more traces:
46 it generates a `run` command line and executes it. You can use its
47 manopt:babeltrace-convert(1):--run-args or
48 manopt:babeltrace-convert(1):--run-args-0 option to make it print the
49 equivalent `run` command line instead.
55 To create a component, use the opt:--component option. This option
58 * **Optional**: The name of the component instance. You can also use the
59 opt:--name option for this.
61 * The type of the component class to instantiate: source, filter, or
64 * The name of the plugin in which to find the component class to
67 * The name of the component class to instantiate.
69 You can use the opt:--component option multiple times to create
70 multiple components. You can instantiate the same component class
71 multiple times as different component instances.
73 At any point in the command line, the opt:--base-params sets the current
74 base initialization parameters and the opt:--reset-base-params resets
75 them. When you specify a opt:--component option, its initial
76 initialization parameters are a copy of the current base initialization
79 Immediately following a opt:--component option on the command line, the
80 created component is known as the _current component_ (until the next
81 opt:--component option).
83 The following, optional command-line options apply to the current
87 Set the name of the current component to 'NAME'.
89 opt:--params='PARAMS'::
90 Add 'PARAMS' to the initialization parameters of the current
91 component. If 'PARAMS' contains a key which exists in the current
92 component's initialization parameters, this parameter is replaced.
94 See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
100 The components which you create from component classes with the
101 opt:--component option (see <<create-comps,Create components>>) can
102 create input and output _ports_ depending on their type. An output port
103 is where notifications, like trace events, are sent. An input port is
104 where notifications are received. For a given component instance, each
105 port has a unique name.
107 The purpose of the `run` command is to create a trace processing graph,
108 that is, to know which component ports to connect together. The command
109 achieves this with the help of the connection rules that you provide
110 with the opt:--connect option.
112 The format of a connection rule (the argument of the opt:--connect
116 __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
119 Upstream component name pattern.
122 Upstream port name pattern.
125 Downstream component name pattern.
128 Downstream port name pattern.
130 When a source or filter component adds a new output port within the
131 processing graph, the `run` command does the following to find an
132 input port to connect it to:
135 For each connection rule:
136 If the output port's component's name matches UP-COMP-PAT and
137 the output port's name matches UP-PORT-PAT:
138 For each component COMP in the processing graph:
139 If the name of COMP matches DOWN-COMP-PAT:
140 Select the first input port of COMP of which the name
141 matches DOWN-PORT-PAT, or fail with no match.
145 __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
146 __DOWN-PORT-PAT__ are globbing patterns where only the wildcard
147 character, `*`, is special: it matches zero or more characters. You must
148 escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:.
150 When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are
153 You can leverage this connection mechanism to specify fallbacks with a
154 careful use of wildcards. For example:
157 --connect='A.out*:B.in*' --connect=A:B --connect='*:C'
160 With those connection rules:
162 * Any output port of which the name starts with `out` of component `A`
163 is connected to the first input port of which the name starts with
164 `in` of component `B`.
166 * Any other output port of component `A` is connected to the first
167 available input port of component `B`.
169 * Any other output port (of any component except `A`) is connected to
170 the first available input port of component `C`.
172 The `run` command fails when it cannot find an input port to which to
173 connect a created output port using the provided connection
176 See <<examples,EXAMPLES>> for more examples.
179 include::common-cmd-params-format.txt[]
181 include::common-cmd-plugin-path.txt[]
186 include::common-gen-options.txt[]
191 opt:-b 'PARAMS', opt:--base-params='PARAMS'::
192 Set the current base parameters to 'PARAMS'. You can reset the
193 current base parameters with the opt:--reset-base-params option.
194 See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
196 opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
197 Create a component initially named 'NAME' (if specified) from the
198 component class of type 'TYPE' named 'COMPCLS' found in the plugin
199 named 'PLUGIN', and set it as the current component.
201 The available values for 'TYPE' are:
206 Source component class.
210 Filter component class.
213 Sink component class.
216 The initial initialization parameters of this component are copied from
217 the current base initialization parameters (see the opt:--base-params
221 Set the name of the current component to 'NAME'. The names of all
222 the components in the processing graph must be unique.
224 opt:-p 'PARAMS', opt:--params='PARAMS'::
225 Add 'PARAMS' to the initialization parameters of the current
226 component. If 'PARAMS' contains a key which exists in the current
227 component's initialization parameters, replace the parameter.
228 See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
230 opt:-r, opt:--reset-base-params::
231 Reset the current base parameters. You can set the current base
232 parameters with the opt:--base-params option.
237 opt:-x 'CONN-RULE', opt:--connect='CONN-RULE'::
238 Add the connection rule 'CONN-RULE'. See
239 <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
244 opt:--retry-duration='DURUS'::
245 Set the duration of a single retry to 'DURUS'{nbsp}µs when a
246 component reports "try again later" (busy network or file system,
249 Default: 100000 (100{nbsp}ms).
252 include::common-plugin-path-options.txt[]
254 include::common-cmd-info-options.txt[]
260 .Create a single-port source component and a single-port sink component and connect them.
264 $ babeltrace run --component=A:src.plug.my-src \
265 --component=B:sink.plug.my-sink \
269 Possible resulting graph:
272 +-----------------+ +-------------------+
273 | src.plug.my-src | | sink.plug.my-sink |
277 +-----------------+ +-------------------+
281 .Use the opt:--name option to name the current component.
285 $ babeltrace run --component=src.plug.my-src --name=the-source \
286 --component=the-sink:sink.plug.my-sink \
287 --connect=the-source:the-sink
291 .Use the opt:--params option to set the current component's initialization parameters.
293 In this example, the opt:--params option only applies to component
298 $ babeltrace run --component=the-source:src.my-plugin.my-src \
299 --params='offset=123, flag=true' \
300 --component=the-sink:sink.my-plugin.my-sink \
301 --connect=the-source:the-sink
305 .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters.
307 In this example, the effective initialization parameters of the
308 created components are:
310 * Component `A`: `offset=1203, flag=false`
311 * Component `B`: `offset=1203, flag=true, type=event`
312 * Component `C`: `ratio=0.25`
316 $ babeltrace run --base-params='offset=1203, flag=false' \
317 --component=A:src.plugin.compcls \
318 --component=B:flt.plugin.compcls \
319 --params='flag=true, type=event' \
320 --reset-base-params \
321 --component=C:sink.plugin.compcls \
322 --params='ratio=0.25' \
323 --connect=A:B --connect=B:C
327 .Specify a component connection fallback rule.
329 In this example, any `A` output port of which the name starts with
330 `foo` is connected to a `B` input port of which the name starts with
331 `nin`. Any other `A` output port is connected to a `B` input port of
332 which the name starts with `oth`.
334 The order of the opt:--connect options is important here: the opposite
335 order would create a system in which the first rule is always satisfied,
336 and _any_ `A` output port, whatever its name, would be connected to a
337 `B` input port with a name that starts with `oth`.
341 $ babeltrace run --component=A:src.plug.my-src \
342 --component=B:sink.plug.my-sink \
343 --connect='A.foo*:B:nin*' --connect='A:B.oth*'
346 Possible resulting graph:
349 +-----------------+ +-------------------+
350 | src.plug.my-src | | sink.plug.my-sink |
354 | foodies @--->@ ninja |
355 | some-port @--->@ othello |
356 | hello @--->@ other |
357 +-----------------+ +-------------------+
362 include::common-cli-env.txt[]
364 include::common-cli-files.txt[]
366 include::common-cmd-footer.txt[]
372 man:babeltrace-convert(1),
373 man:babeltrace-intro(7)