Commit | Line | Data |
---|---|---|
838dd456 PP |
1 | babeltrace-run(1) |
2 | ================= | |
3 | :manpagetype: command | |
4 | :revdate: 5 October 2017 | |
5 | ||
6 | ||
7 | NAME | |
8 | ---- | |
9 | babeltrace-run - Create a trace processing graph and run it | |
10 | ||
11 | ||
12 | SYNOPSIS | |
13 | -------- | |
14 | [verse] | |
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' | |
20 | ||
21 | ||
22 | DESCRIPTION | |
23 | ----------- | |
24 | The `run` command creates a trace processing graph and runs it. | |
25 | ||
26 | See man:babeltrace-intro(7) to learn more about the Babeltrace | |
27 | project and its core concepts. | |
28 | ||
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 | |
32 | connected. | |
33 | ||
34 | The steps to write a `babeltrace run` command line are: | |
35 | ||
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. | |
39 | ||
40 | . Specify how to connect component instances together with one or more | |
41 | opt:--connect options. See <<connect-comps,Connect components>> to | |
42 | learn more. | |
43 | ||
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. | |
50 | ||
51 | ||
52 | [[create-comps]] | |
53 | Create components | |
54 | ~~~~~~~~~~~~~~~~~ | |
55 | To create a component, use the opt:--component option. This option | |
56 | specifies: | |
57 | ||
58 | * **Optional**: The name of the component instance. You can also use the | |
59 | opt:--name option for this. | |
60 | ||
61 | * The type of the component class to instantiate: source, filter, or | |
62 | sink. | |
63 | ||
64 | * The name of the plugin in which to find the component class to | |
65 | instantiate. | |
66 | ||
67 | * The name of the component class to instantiate. | |
68 | ||
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. | |
72 | ||
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 | |
77 | parameters. | |
78 | ||
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). | |
82 | ||
83 | The following, optional command-line options apply to the current | |
84 | component: | |
85 | ||
86 | opt:--name='NAME':: | |
87 | Set the name of the current component to 'NAME'. | |
88 | ||
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. | |
93 | + | |
94 | See <<params-fmt,Parameters format>> for the format of 'PARAMS'. | |
95 | ||
96 | opt:--key='KEY' followed with opt:--value='VALUE':: | |
97 | Set the current component's initialization parameter named 'KEY' to | |
98 | the string value 'VALUE'. If 'KEY' exists in the current component's | |
99 | initialization parameters, the parameter is replaced. | |
100 | ||
101 | ||
102 | [[connect-comps]] | |
103 | Connect components | |
104 | ~~~~~~~~~~~~~~~~~~ | |
105 | The components which you create from component classes with the | |
106 | opt:--component option (see <<create-comps,Create components>>) can | |
107 | create input and output _ports_ depending on their type. An output port | |
108 | is where notifications, like trace events, are sent. An input port is | |
109 | where notifications are received. For a given component instance, each | |
110 | port has a unique name. | |
111 | ||
112 | The purpose of the `run` command is to create a trace processing graph, | |
113 | that is, to know which component ports to connect together. The command | |
114 | achieves this with the help of the connection rules that you provide | |
115 | with the opt:--connect option. | |
116 | ||
117 | The format of a connection rule (the argument of the opt:--connect | |
118 | option) is: | |
119 | ||
120 | [verse] | |
121 | __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] | |
122 | ||
123 | 'UP-COMP-PATH':: | |
124 | Upstream component name pattern. | |
125 | ||
126 | 'UP-PORT-PAT':: | |
127 | Upstream port name pattern. | |
128 | ||
129 | 'DOWN-COMP-PATH':: | |
130 | Downstream component name pattern. | |
131 | ||
132 | 'DOWN-PORT-PAT':: | |
133 | Downstream port name pattern. | |
134 | ||
135 | When a source or filter component adds a new output port within the | |
136 | processing graph, the `run` command does the following to find an | |
137 | input port to connect it to: | |
138 | ||
139 | ---- | |
140 | For each connection rule: | |
141 | If the output port's component's name matches UP-COMP-PAT and | |
142 | the output port's name matches UP-PORT-PAT: | |
143 | For each component COMP in the processing graph: | |
144 | If the name of COMP matches DOWN-COMP-PAT: | |
145 | Select the first input port of COMP of which the name | |
146 | matches DOWN-PORT-PAT, or fail with no match. | |
147 | Fail with no match. | |
148 | ---- | |
149 | ||
150 | __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and | |
151 | __DOWN-PORT-PAT__ are globbing patterns where only the wildcard | |
152 | character, `*`, is special: it matches zero or more characters. You must | |
153 | escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:. | |
154 | ||
155 | When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are | |
156 | equivalent to `*`. | |
157 | ||
158 | You can leverage this connection mechanism to specify fallbacks with a | |
159 | careful use of wildcards. For example: | |
160 | ||
161 | ---- | |
162 | --connect='A.out*:B.in*' --connect=A:B --connect='*:C' | |
163 | ---- | |
164 | ||
165 | With those connection rules: | |
166 | ||
167 | * Any output port of which the name starts with `out` of component `A` | |
168 | is connected to the first input port of which the name starts with | |
169 | `in` of component `B`. | |
170 | ||
171 | * Any other output port of component `A` is connected to the first | |
172 | available input port of component `B`. | |
173 | ||
174 | * Any other output port (of any component except `A`) is connected to | |
175 | the first available input port of component `C`. | |
176 | ||
177 | The `run` command fails when it cannot find an input port to which to | |
178 | connect a created output port using the provided connection | |
179 | rules. | |
180 | ||
181 | See <<examples,EXAMPLES>> for more examples. | |
182 | ||
183 | ||
184 | include::common-cmd-params-format.txt[] | |
185 | ||
186 | include::common-cmd-plugin-path.txt[] | |
187 | ||
188 | ||
189 | OPTIONS | |
190 | ------- | |
191 | include::common-gen-options.txt[] | |
192 | ||
193 | ||
194 | Component creation | |
195 | ~~~~~~~~~~~~~~~~~~ | |
196 | opt:-b 'PARAMS', opt:--base-params='PARAMS':: | |
197 | Set the current base parameters to 'PARAMS'. You can reset the | |
198 | current base parameters with the opt:--reset-base-params option. | |
199 | See <<params-fmt,Parameters format>> for the format of 'PARAMS'. | |
200 | ||
201 | opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS':: | |
202 | Create a component initially named 'NAME' (if specified) from the | |
203 | component class of type 'TYPE' named 'COMPCLS' found in the plugin | |
204 | named 'PLUGIN', and set it as the current component. | |
205 | + | |
206 | The available values for 'TYPE' are: | |
207 | + | |
208 | -- | |
209 | `source`:: | |
210 | `src`:: | |
211 | Source component class. | |
212 | ||
213 | `filter`:: | |
214 | `flt`:: | |
215 | Filter component class. | |
216 | ||
217 | `sink`:: | |
218 | Sink component class. | |
219 | -- | |
220 | + | |
221 | The initial initialization parameters of this component are copied from | |
222 | the current base initialization parameters (see the opt:--base-params | |
223 | option). | |
224 | ||
225 | opt:--key='KEY':: | |
226 | Set the current parameter key to 'KEY'. The next opt:--value option | |
227 | uses this key to add a parameter to the current component. | |
228 | ||
229 | opt:--name='NAME':: | |
230 | Set the name of the current component to 'NAME'. The names of all | |
231 | the components in the processing graph must be unique. | |
232 | ||
233 | opt:-p 'PARAMS', opt:--params='PARAMS':: | |
234 | Add 'PARAMS' to the initialization parameters of the current | |
235 | component. If 'PARAMS' contains a key which exists in the current | |
236 | component's initialization parameters, replace the parameter. | |
237 | See <<params-fmt,Parameters format>> for the format of 'PARAMS'. | |
238 | ||
239 | opt:-r, opt:--reset-base-params:: | |
240 | Reset the current base parameters. You can set the current base | |
241 | parameters with the opt:--base-params option. | |
242 | ||
243 | opt:-v 'VALUE', opt:--value='VALUE':: | |
244 | Add a parameter to the current component's initialization parameters | |
245 | of which the key is the argument of the last opt:--key option and | |
246 | the string value is 'VALUE'. If the current component's | |
247 | initialization parameters already contain a key named 'KEY', replace | |
248 | the parameter. | |
249 | ||
250 | ||
251 | Component connection | |
252 | ~~~~~~~~~~~~~~~~~~~~ | |
253 | opt:-C 'CONN-RULE', opt:--connect='CONN-RULE':: | |
254 | Add the connection rule 'CONN-RULE'. See | |
255 | <<connect-comps,Connect components>> for the format of 'CONN-RULE'. | |
256 | ||
257 | ||
258 | Graph configuration | |
259 | ~~~~~~~~~~~~~~~~~~~ | |
260 | opt:--retry-duration='DURUS':: | |
261 | Set the duration of a single retry to 'DURUS'{nbsp}µs when a | |
262 | component reports "try again later" (busy network or file system, | |
263 | for example). | |
264 | + | |
265 | Default: 100000 (100{nbsp}ms). | |
266 | ||
267 | ||
268 | include::common-plugin-path-options.txt[] | |
269 | ||
270 | include::common-cmd-info-options.txt[] | |
271 | ||
272 | ||
273 | [[examples]] | |
274 | EXAMPLES | |
275 | -------- | |
276 | .Create a single-port source component and a single-port sink component and connect them. | |
277 | ==== | |
278 | [role="term"] | |
279 | ---- | |
280 | $ babeltrace run --component=A:src.plug.my-src \ | |
281 | --component=B:sink.plug.my-sink \ | |
282 | --connect=A:B | |
283 | ---- | |
284 | ||
285 | Possible resulting graph: | |
286 | ||
287 | ---- | |
288 | +-----------------+ +-------------------+ | |
289 | | src.plug.my-src | | sink.plug.my-sink | | |
290 | | [A] | | [B] | | |
291 | | | | | | |
292 | | out @--->@ in | | |
293 | +-----------------+ +-------------------+ | |
294 | ---- | |
295 | ==== | |
296 | ||
297 | .Use the opt:--name option to name the current component. | |
298 | ==== | |
299 | [role="term"] | |
300 | ---- | |
301 | $ babeltrace run --component=src.plug.my-src --name=the-source \ | |
302 | --component=the-sink:sink.plug.my-sink \ | |
303 | --connect=the-source:the-sink | |
304 | ---- | |
305 | ==== | |
306 | ||
307 | .Use the opt:--params option to set the current component's initialization parameters. | |
308 | ==== | |
309 | In this example, the opt:--params option only applies to component | |
310 | `the-source`. | |
311 | ||
312 | [role="term"] | |
313 | ---- | |
314 | $ babeltrace run --component=the-source:src.my-plugin.my-src \ | |
315 | --params='offset=123, flag=true' \ | |
316 | --component=the-sink:sink.my-plugin.my-sink \ | |
317 | --connect=the-source:the-sink | |
318 | ---- | |
319 | ==== | |
320 | ||
321 | .Use the opt:--key and opt:--value options to set a current component's initialization parameter. | |
322 | ==== | |
323 | [role="term"] | |
324 | ---- | |
325 | $ babeltrace run --component=the-source:src.my-plugin.my-src \ | |
326 | --key=path --value ~/my-traces/the-trace | |
327 | --component=the-sink:sink.my-plugin.my-sink \ | |
328 | --connect=the-source:the-sink | |
329 | ---- | |
330 | ==== | |
331 | ||
332 | .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters. | |
333 | ==== | |
334 | In this example, the effective initialization parameters of the | |
335 | created components are: | |
336 | ||
337 | * Component `A`: `offset=1203, flag=false` | |
338 | * Component `B`: `offset=1203, flag=true, type=event` | |
339 | * Component `C`: `ratio=0.25` | |
340 | ||
341 | [role="term"] | |
342 | ---- | |
343 | $ babeltrace run --base-params='offset=1203, flag=false' \ | |
344 | --component=A:src.plugin.compcls \ | |
345 | --component=B:flt.plugin.compcls \ | |
346 | --params='flag=true, type=event' \ | |
347 | --reset-base-params \ | |
348 | --component=C:sink.plugin.compcls \ | |
349 | --params='ratio=0.25' \ | |
350 | --connect=A:B --connect=B:C | |
351 | ---- | |
352 | ==== | |
353 | ||
354 | .Specify a component connection fallback rule. | |
355 | ==== | |
356 | In this example, any `A` output port of which the name starts with | |
357 | `foo` is connected to a `B` input port of which the name starts with | |
358 | `nin`. Any other `A` output port is connected to a `B` input port of | |
359 | which the name starts with `oth`. | |
360 | ||
361 | The order of the opt:--connect options is important here: the opposite | |
362 | order would create a system in which the first rule is always satisfied, | |
363 | and _any_ `A` output port, whatever its name, would be connected to a | |
364 | `B` input port with a name that starts with `oth`. | |
365 | ||
366 | [role="term"] | |
367 | ---- | |
368 | $ babeltrace run --component=A:src.plug.my-src \ | |
369 | --component=B:sink.plug.my-sink \ | |
370 | --connect='A.foo*:B:nin*' --connect='A:B.oth*' | |
371 | ---- | |
372 | ||
373 | Possible resulting graph: | |
374 | ||
375 | ---- | |
376 | +-----------------+ +-------------------+ | |
377 | | src.plug.my-src | | sink.plug.my-sink | | |
378 | | [A] | | [B] | | |
379 | | | | | | |
380 | | foot @--->@ nine | | |
381 | | foodies @--->@ ninja | | |
382 | | some-port @--->@ othello | | |
383 | | hello @--->@ other | | |
384 | +-----------------+ +-------------------+ | |
385 | ---- | |
386 | ==== | |
387 | ||
388 | ||
389 | include::common-cli-env.txt[] | |
390 | ||
391 | include::common-cli-files.txt[] | |
392 | ||
393 | include::common-cmd-footer.txt[] | |
394 | ||
395 | ||
396 | SEE ALSO | |
397 | -------- | |
398 | man:babeltrace(1), | |
399 | man:babeltrace-convert(1), | |
400 | man:babeltrace-intro(7) |