Commit | Line | Data |
---|---|---|
2facbdc3 | 1 | = babeltrace2-run(1) |
838dd456 | 2 | :manpagetype: command |
2facbdc3 | 3 | :revdate: 14 September 2019 |
838dd456 PP |
4 | |
5 | ||
2facbdc3 PP |
6 | == NAME |
7 | ||
8 | babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it | |
838dd456 PP |
9 | |
10 | ||
2facbdc3 PP |
11 | [[synopsis]] |
12 | == SYNOPSIS | |
13 | ||
838dd456 | 14 | [verse] |
2facbdc3 PP |
15 | *babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *run* [opt:--retry-duration='TIME-US'] |
16 | opt:--connect='CONN-RULE'... 'COMPONENTS' | |
17 | ||
838dd456 | 18 | |
2facbdc3 | 19 | == DESCRIPTION |
838dd456 | 20 | |
2facbdc3 PP |
21 | The `run` command creates a Babeltrace~2 trace processing graph and |
22 | runs it. | |
838dd456 | 23 | |
2facbdc3 | 24 | include::common-see-babeltrace2-intro.txt[] |
838dd456 | 25 | |
2facbdc3 | 26 | The `run` command dynamically loads Babeltrace~2 plugins which |
838dd456 | 27 | supply component classes. With the `run` command, you specify which |
2facbdc3 | 28 | component classes to instantiate as components and how to connect them. |
838dd456 | 29 | |
c1f82f3b | 30 | The steps to write a `babeltrace2 run` command line are: |
838dd456 | 31 | |
2facbdc3 PP |
32 | . Specify which component classes to instantiate as components with many |
33 | opt:--component options and how to configure them. | |
34 | + | |
35 | This is the 'COMPONENTS' part of the <<synopsis,synopsis>>. See | |
36 | <<create-comps,``Create components''>> to learn more. | |
838dd456 | 37 | |
2facbdc3 PP |
38 | . Specify how to connect components together with one or more |
39 | opt:--connect options. | |
40 | + | |
41 | See <<connect-comps,``Connect components''>> to learn more. | |
838dd456 | 42 | |
c1f82f3b | 43 | NOTE: The man:babeltrace2-convert(1) command is a specialization of the |
838dd456 PP |
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 | |
c1f82f3b MJ |
46 | manopt:babeltrace2-convert(1):--run-args or |
47 | manopt:babeltrace2-convert(1):--run-args-0 option to make it print the | |
838dd456 PP |
48 | equivalent `run` command line instead. |
49 | ||
50 | ||
51 | [[create-comps]] | |
2facbdc3 PP |
52 | === Create components |
53 | ||
838dd456 PP |
54 | To create a component, use the opt:--component option. This option |
55 | specifies: | |
56 | ||
2facbdc3 PP |
57 | * The name of the component, unique amongst all the component names of |
58 | the trace processing graph. | |
838dd456 PP |
59 | |
60 | * The type of the component class to instantiate: source, filter, or | |
61 | sink. | |
62 | ||
63 | * The name of the plugin in which to find the component class to | |
64 | instantiate. | |
65 | ||
66 | * The name of the component class to instantiate. | |
67 | ||
2facbdc3 PP |
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. | |
838dd456 PP |
71 | |
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 | |
76 | parameters. | |
77 | ||
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). | |
81 | ||
2facbdc3 PP |
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. | |
838dd456 | 86 | |
838dd456 PP |
87 | |
88 | [[connect-comps]] | |
2facbdc3 PP |
89 | === Connect components |
90 | ||
838dd456 | 91 | The components which you create from component classes with the |
2facbdc3 PP |
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 | |
96 | name. | |
838dd456 PP |
97 | |
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 | |
2facbdc3 | 101 | with one or more opt:--connect='CONN-RULE' options. |
838dd456 | 102 | |
2facbdc3 | 103 | The format of 'CONN-RULE' is: |
838dd456 PP |
104 | |
105 | [verse] | |
106 | __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] | |
107 | ||
2facbdc3 | 108 | 'UP-COMP-PAT':: |
838dd456 PP |
109 | Upstream component name pattern. |
110 | ||
111 | 'UP-PORT-PAT':: | |
2facbdc3 | 112 | Upstream (output) port name pattern. |
838dd456 | 113 | |
2facbdc3 | 114 | 'DOWN-COMP-PAT':: |
838dd456 PP |
115 | Downstream component name pattern. |
116 | ||
117 | 'DOWN-PORT-PAT':: | |
2facbdc3 | 118 | Downstream (input) port name pattern. |
838dd456 PP |
119 | |
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: | |
123 | ||
124 | ---- | |
2facbdc3 PP |
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: | |
838dd456 | 129 | If the name of COMP matches DOWN-COMP-PAT: |
2facbdc3 PP |
130 | Select the first input port of COMP of which the name matches |
131 | DOWN-PORT-PAT, or fail with no match. | |
132 | ||
133 | No possible connection: fail with no match. | |
838dd456 PP |
134 | ---- |
135 | ||
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:. | |
140 | ||
141 | When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are | |
142 | equivalent to `*`. | |
143 | ||
144 | You can leverage this connection mechanism to specify fallbacks with a | |
2facbdc3 PP |
145 | careful use of wildcards, as the order of the opt:--connect options on |
146 | the command line is significant. For example: | |
838dd456 PP |
147 | |
148 | ---- | |
149 | --connect='A.out*:B.in*' --connect=A:B --connect='*:C' | |
150 | ---- | |
151 | ||
2facbdc3 | 152 | With those connection rules, the `run` command connects: |
838dd456 PP |
153 | |
154 | * Any output port of which the name starts with `out` of component `A` | |
2facbdc3 PP |
155 | to the first input port of which the name starts with `in` of |
156 | component `B`. | |
838dd456 | 157 | |
2facbdc3 PP |
158 | * Any other output port of component `A` to the first available input |
159 | port of component `B`. | |
838dd456 | 160 | |
2facbdc3 PP |
161 | * Any other output port (of any component except `A`) to the first |
162 | available input port of component `C`. | |
838dd456 PP |
163 | |
164 | The `run` command fails when it cannot find an input port to which to | |
2facbdc3 | 165 | connect a given output port using the provided connection rules. |
838dd456 | 166 | |
2facbdc3 | 167 | See <<examples,``EXAMPLES''>> for more examples. |
838dd456 PP |
168 | |
169 | ||
2facbdc3 | 170 | == OPTIONS |
838dd456 | 171 | |
2facbdc3 | 172 | include::common-gen-options.txt[] |
838dd456 PP |
173 | |
174 | ||
2facbdc3 | 175 | === Component creation |
838dd456 | 176 | |
2facbdc3 | 177 | See <<create-comps,``Create components''>> for more details. |
838dd456 | 178 | |
2facbdc3 PP |
179 | opt:-b 'PARAMS':: |
180 | opt:--base-params='PARAMS':: | |
181 | Set the current base parameters to 'PARAMS'. | |
182 | + | |
183 | You can reset the current base parameters with the | |
184 | opt:--reset-base-params option. | |
185 | + | |
186 | See the opt:--params option for the format of 'PARAMS'. | |
838dd456 | 187 | |
2facbdc3 PP |
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. | |
838dd456 PP |
193 | + |
194 | The available values for 'TYPE' are: | |
195 | + | |
196 | -- | |
197 | `source`:: | |
198 | `src`:: | |
199 | Source component class. | |
200 | ||
201 | `filter`:: | |
202 | `flt`:: | |
203 | Filter component class. | |
204 | ||
205 | `sink`:: | |
206 | Sink component class. | |
207 | -- | |
208 | + | |
209 | The initial initialization parameters of this component are copied from | |
210 | the current base initialization parameters (see the opt:--base-params | |
211 | option). | |
212 | ||
2facbdc3 PP |
213 | opt:-l 'LVL':: |
214 | opt:--log-level='LVL':: | |
215 | Set the log level of the current component to 'LVL'. | |
216 | + | |
217 | The available values for 'LVL' are: | |
218 | + | |
219 | -- | |
220 | include::common-log-levels.txt[] | |
221 | -- | |
838dd456 | 222 | |
2facbdc3 PP |
223 | opt:-p 'PARAMS':: |
224 | opt:--params='PARAMS':: | |
838dd456 | 225 | Add 'PARAMS' to the initialization parameters of the current |
2facbdc3 PP |
226 | component. |
227 | + | |
228 | If 'PARAMS' contains a key which exists in the current component's | |
229 | initialization parameters, replace the parameter. | |
230 | + | |
231 | -- | |
232 | include::common-cmd-params-format.txt[] | |
233 | -- | |
234 | ||
235 | opt:-r:: | |
236 | opt:--reset-base-params:: | |
237 | Reset the current base parameters. | |
238 | + | |
239 | You can set the current base parameters with the opt:--base-params | |
240 | option. | |
241 | ||
838dd456 | 242 | |
2facbdc3 | 243 | === Component connection |
838dd456 | 244 | |
2facbdc3 PP |
245 | opt:-x 'CONN-RULE':: |
246 | opt:--connect='CONN-RULE':: | |
247 | Add the connection rule 'CONN-RULE'. | |
248 | + | |
249 | The format of 'CONN-RULE' is: | |
250 | + | |
251 | [verse] | |
252 | __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] | |
253 | + | |
254 | -- | |
255 | 'UP-COMP-PAT':: | |
256 | Upstream component name pattern. | |
257 | ||
258 | 'UP-PORT-PAT':: | |
259 | Upstream (output) port name pattern. | |
260 | ||
261 | 'DOWN-COMP-PAT':: | |
262 | Downstream component name pattern. | |
263 | ||
264 | 'DOWN-PORT-PAT':: | |
265 | Downstream (input) port name pattern. | |
266 | -- | |
267 | + | |
268 | See <<connect-comps,``Connect components''>> to learn more. | |
838dd456 | 269 | |
838dd456 | 270 | |
2facbdc3 | 271 | === Graph configuration |
838dd456 | 272 | |
2facbdc3 PP |
273 | opt:--retry-duration='TIME-US':: |
274 | Set the duration of a single retry to 'TIME-US'~µs when a sink | |
838dd456 PP |
275 | component reports "try again later" (busy network or file system, |
276 | for example). | |
277 | + | |
2facbdc3 | 278 | Default: 100000 (100~ms). |
838dd456 PP |
279 | |
280 | ||
838dd456 PP |
281 | include::common-cmd-info-options.txt[] |
282 | ||
283 | ||
284 | [[examples]] | |
2facbdc3 PP |
285 | == EXAMPLES |
286 | ||
838dd456 PP |
287 | .Create a single-port source component and a single-port sink component and connect them. |
288 | ==== | |
289 | [role="term"] | |
290 | ---- | |
c1f82f3b | 291 | $ babeltrace2 run --component=A:src.plug.my-src \ |
2facbdc3 PP |
292 | --component=B:sink.plug.my-sink \ |
293 | --connect=A:B | |
838dd456 PP |
294 | ---- |
295 | ||
296 | Possible resulting graph: | |
297 | ||
298 | ---- | |
299 | +-----------------+ +-------------------+ | |
300 | | src.plug.my-src | | sink.plug.my-sink | | |
301 | | [A] | | [B] | | |
302 | | | | | | |
303 | | out @--->@ in | | |
304 | +-----------------+ +-------------------+ | |
305 | ---- | |
306 | ==== | |
307 | ||
838dd456 PP |
308 | .Use the opt:--params option to set the current component's initialization parameters. |
309 | ==== | |
310 | In this example, the opt:--params option only applies to component | |
311 | `the-source`. | |
312 | ||
313 | [role="term"] | |
314 | ---- | |
c1f82f3b | 315 | $ babeltrace2 run --component=the-source:src.my-plugin.my-src \ |
2facbdc3 PP |
316 | --params=offset=123,flag=true \ |
317 | --component=the-sink:sink.my-plugin.my-sink \ | |
318 | --connect=the-source:the-sink | |
838dd456 PP |
319 | ---- |
320 | ==== | |
321 | ||
838dd456 PP |
322 | .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters. |
323 | ==== | |
324 | In this example, the effective initialization parameters of the | |
325 | created components are: | |
326 | ||
2facbdc3 PP |
327 | Component `A`:: |
328 | `offset=1203, flag=false` | |
329 | ||
330 | Component `B`:: | |
331 | `offset=1203, flag=true, type=event` | |
332 | ||
333 | Component `C`:: | |
334 | `ratio=0.25` | |
838dd456 PP |
335 | |
336 | [role="term"] | |
337 | ---- | |
2facbdc3 PP |
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 | |
838dd456 PP |
346 | ---- |
347 | ==== | |
348 | ||
349 | .Specify a component connection fallback rule. | |
350 | ==== | |
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`. | |
355 | ||
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`. | |
360 | ||
361 | [role="term"] | |
362 | ---- | |
c1f82f3b | 363 | $ babeltrace2 run --component=A:src.plug.my-src \ |
2facbdc3 PP |
364 | --component=B:sink.plug.my-sink \ |
365 | --connect='A.foo*:B:nin*' --connect='A:B.oth*' | |
838dd456 PP |
366 | ---- |
367 | ||
368 | Possible resulting graph: | |
369 | ||
370 | ---- | |
371 | +-----------------+ +-------------------+ | |
372 | | src.plug.my-src | | sink.plug.my-sink | | |
373 | | [A] | | [B] | | |
374 | | | | | | |
375 | | foot @--->@ nine | | |
376 | | foodies @--->@ ninja | | |
377 | | some-port @--->@ othello | | |
378 | | hello @--->@ other | | |
379 | +-----------------+ +-------------------+ | |
380 | ---- | |
381 | ==== | |
382 | ||
383 | ||
384 | include::common-cli-env.txt[] | |
385 | ||
2facbdc3 | 386 | |
838dd456 PP |
387 | include::common-cli-files.txt[] |
388 | ||
2facbdc3 | 389 | |
838dd456 PP |
390 | include::common-cmd-footer.txt[] |
391 | ||
392 | ||
2facbdc3 PP |
393 | == SEE ALSO |
394 | ||
395 | man:babeltrace2-intro(7), | |
c1f82f3b | 396 | man:babeltrace2(1), |
2facbdc3 | 397 | man:babeltrace2-convert(1) |