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 | ||
838dd456 PP |
96 | |
97 | [[connect-comps]] | |
98 | Connect components | |
99 | ~~~~~~~~~~~~~~~~~~ | |
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. | |
106 | ||
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. | |
111 | ||
112 | The format of a connection rule (the argument of the opt:--connect | |
113 | option) is: | |
114 | ||
115 | [verse] | |
116 | __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] | |
117 | ||
118 | 'UP-COMP-PATH':: | |
119 | Upstream component name pattern. | |
120 | ||
121 | 'UP-PORT-PAT':: | |
122 | Upstream port name pattern. | |
123 | ||
124 | 'DOWN-COMP-PATH':: | |
125 | Downstream component name pattern. | |
126 | ||
127 | 'DOWN-PORT-PAT':: | |
128 | Downstream port name pattern. | |
129 | ||
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: | |
133 | ||
134 | ---- | |
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. | |
142 | Fail with no match. | |
143 | ---- | |
144 | ||
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:. | |
149 | ||
150 | When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are | |
151 | equivalent to `*`. | |
152 | ||
153 | You can leverage this connection mechanism to specify fallbacks with a | |
154 | careful use of wildcards. For example: | |
155 | ||
156 | ---- | |
157 | --connect='A.out*:B.in*' --connect=A:B --connect='*:C' | |
158 | ---- | |
159 | ||
160 | With those connection rules: | |
161 | ||
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`. | |
165 | ||
166 | * Any other output port of component `A` is connected to the first | |
167 | available input port of component `B`. | |
168 | ||
169 | * Any other output port (of any component except `A`) is connected to | |
170 | the first available input port of component `C`. | |
171 | ||
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 | |
174 | rules. | |
175 | ||
176 | See <<examples,EXAMPLES>> for more examples. | |
177 | ||
178 | ||
179 | include::common-cmd-params-format.txt[] | |
180 | ||
181 | include::common-cmd-plugin-path.txt[] | |
182 | ||
183 | ||
184 | OPTIONS | |
185 | ------- | |
186 | include::common-gen-options.txt[] | |
187 | ||
188 | ||
189 | Component creation | |
190 | ~~~~~~~~~~~~~~~~~~ | |
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'. | |
195 | ||
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. | |
200 | + | |
201 | The available values for 'TYPE' are: | |
202 | + | |
203 | -- | |
204 | `source`:: | |
205 | `src`:: | |
206 | Source component class. | |
207 | ||
208 | `filter`:: | |
209 | `flt`:: | |
210 | Filter component class. | |
211 | ||
212 | `sink`:: | |
213 | Sink component class. | |
214 | -- | |
215 | + | |
216 | The initial initialization parameters of this component are copied from | |
217 | the current base initialization parameters (see the opt:--base-params | |
218 | option). | |
219 | ||
838dd456 PP |
220 | opt:--name='NAME':: |
221 | Set the name of the current component to 'NAME'. The names of all | |
222 | the components in the processing graph must be unique. | |
223 | ||
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'. | |
229 | ||
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. | |
233 | ||
838dd456 PP |
234 | |
235 | Component connection | |
236 | ~~~~~~~~~~~~~~~~~~~~ | |
d5128b09 | 237 | opt:-x 'CONN-RULE', opt:--connect='CONN-RULE':: |
838dd456 PP |
238 | Add the connection rule 'CONN-RULE'. See |
239 | <<connect-comps,Connect components>> for the format of 'CONN-RULE'. | |
240 | ||
241 | ||
242 | Graph configuration | |
243 | ~~~~~~~~~~~~~~~~~~~ | |
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, | |
247 | for example). | |
248 | + | |
249 | Default: 100000 (100{nbsp}ms). | |
250 | ||
251 | ||
252 | include::common-plugin-path-options.txt[] | |
253 | ||
254 | include::common-cmd-info-options.txt[] | |
255 | ||
256 | ||
257 | [[examples]] | |
258 | EXAMPLES | |
259 | -------- | |
260 | .Create a single-port source component and a single-port sink component and connect them. | |
261 | ==== | |
262 | [role="term"] | |
263 | ---- | |
264 | $ babeltrace run --component=A:src.plug.my-src \ | |
265 | --component=B:sink.plug.my-sink \ | |
266 | --connect=A:B | |
267 | ---- | |
268 | ||
269 | Possible resulting graph: | |
270 | ||
271 | ---- | |
272 | +-----------------+ +-------------------+ | |
273 | | src.plug.my-src | | sink.plug.my-sink | | |
274 | | [A] | | [B] | | |
275 | | | | | | |
276 | | out @--->@ in | | |
277 | +-----------------+ +-------------------+ | |
278 | ---- | |
279 | ==== | |
280 | ||
281 | .Use the opt:--name option to name the current component. | |
282 | ==== | |
283 | [role="term"] | |
284 | ---- | |
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 | |
288 | ---- | |
289 | ==== | |
290 | ||
291 | .Use the opt:--params option to set the current component's initialization parameters. | |
292 | ==== | |
293 | In this example, the opt:--params option only applies to component | |
294 | `the-source`. | |
295 | ||
296 | [role="term"] | |
297 | ---- | |
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 | |
302 | ---- | |
303 | ==== | |
304 | ||
838dd456 PP |
305 | .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters. |
306 | ==== | |
307 | In this example, the effective initialization parameters of the | |
308 | created components are: | |
309 | ||
310 | * Component `A`: `offset=1203, flag=false` | |
311 | * Component `B`: `offset=1203, flag=true, type=event` | |
312 | * Component `C`: `ratio=0.25` | |
313 | ||
314 | [role="term"] | |
315 | ---- | |
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 | |
324 | ---- | |
325 | ==== | |
326 | ||
327 | .Specify a component connection fallback rule. | |
328 | ==== | |
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`. | |
333 | ||
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`. | |
338 | ||
339 | [role="term"] | |
340 | ---- | |
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*' | |
344 | ---- | |
345 | ||
346 | Possible resulting graph: | |
347 | ||
348 | ---- | |
349 | +-----------------+ +-------------------+ | |
350 | | src.plug.my-src | | sink.plug.my-sink | | |
351 | | [A] | | [B] | | |
352 | | | | | | |
353 | | foot @--->@ nine | | |
354 | | foodies @--->@ ninja | | |
355 | | some-port @--->@ othello | | |
356 | | hello @--->@ other | | |
357 | +-----------------+ +-------------------+ | |
358 | ---- | |
359 | ==== | |
360 | ||
361 | ||
362 | include::common-cli-env.txt[] | |
363 | ||
364 | include::common-cli-files.txt[] | |
365 | ||
366 | include::common-cmd-footer.txt[] | |
367 | ||
368 | ||
369 | SEE ALSO | |
370 | -------- | |
371 | man:babeltrace(1), | |
372 | man:babeltrace-convert(1), | |
373 | man:babeltrace-intro(7) |