1BABELTRACE2-RUN(1) Babeltrace 2 manual BABELTRACE2-RUN(1)
2
3
4
6 babeltrace2-run - Create a Babeltrace 2 trace processing graph and run
7 it
8
10 babeltrace2 [GENERAL OPTIONS] run [--retry-duration=TIME-US]
11 --connect=CONN-RULE... COMPONENTS
12
14 The run command creates a Babeltrace 2 trace processing graph and runs
15 it.
16
17 See babeltrace2-intro(7) to learn more about the Babeltrace 2 project
18 and its core concepts.
19
20 The run command dynamically loads Babeltrace 2 plugins which supply
21 component classes. With the run command, you specify which component
22 classes to instantiate as components and how to connect them.
23
24 The steps to write a babeltrace2 run command line are:
25
26 1. Specify which component classes to instantiate as components with
27 many --component options and how to configure them.
28
29 This is the COMPONENTS part of the synopsis. See “Create
30 components” to learn more.
31
32 2. Specify how to connect components together with one or more
33 --connect options.
34
35 See “Connect components” to learn more.
36
37 Note
38 The babeltrace2-convert(1) command is a specialization of the run
39 command for the very common case of converting one or more traces:
40 it generates a run command line and executes it. You can use its
41 --run-args or --run-args-0 option to make it print the equivalent
42 run command line instead.
43
44 Create components
45 To create a component, use the --component option. This option
46 specifies:
47
48 • The name of the component, unique amongst all the component names
49 of the trace processing graph.
50
51 • The type of the component class to instantiate: source, filter, or
52 sink.
53
54 • The name of the plugin in which to find the component class to
55 instantiate.
56
57 • The name of the component class to instantiate.
58
59 Use the --component option multiple times to create multiple
60 components. You can instantiate the same component class multiple times
61 as different components.
62
63 At any point in the command line, the --base-params sets the current
64 base initialization parameters and the --reset-base-params resets them.
65 When you specify a --component option, its initial initialization
66 parameters are a copy of the current base initialization parameters.
67
68 Immediately following a --component option on the command line, the
69 created component is known as the current component (until the next
70 --component option).
71
72 The --params=PARAMS option adds parameters to the current component’s
73 initialization parameters. If PARAMS contains a key which exists in the
74 current component’s initialization parameters, this parameter is
75 replaced.
76
77 Connect components
78 The components which you create from component classes with the
79 --component option (see “Create components”) add input and output ports
80 depending on their type. An output port is from where messages, like
81 trace events, are sent. An input port is where messages are received.
82 For a given component, each port has a unique name.
83
84 The purpose of the run command is to create a trace processing graph,
85 that is, to know which component ports to connect together. The command
86 achieves this with the help of the connection rules that you provide
87 with one or more --connect=CONN-RULE options.
88
89 The format of CONN-RULE is:
90
91 UP-COMP-PAT[.UP-PORT-PAT]:DOWN-COMP-PAT[.DOWN-PORT-PAT]
92
93 UP-COMP-PAT
94 Upstream component name pattern.
95
96 UP-PORT-PAT
97 Upstream (output) port name pattern.
98
99 DOWN-COMP-PAT
100 Downstream component name pattern.
101
102 DOWN-PORT-PAT
103 Downstream (input) port name pattern.
104
105 When a source or filter component adds a new output port within the
106 processing graph, the run command does the following to find an input
107 port to connect it to:
108
109 For each connection rule (--connect options, in order):
110 If the output port's component's name matches UP-COMP-PAT and the
111 output port's name matches UP-PORT-PAT:
112 For each component COMP in the trace processing graph:
113 If the name of COMP matches DOWN-COMP-PAT:
114 Select the first input port of COMP of which the name matches
115 DOWN-PORT-PAT, or fail with no match.
116
117 No possible connection: fail with no match.
118
119 UP-COMP-PAT, UP-PORT-PAT, DOWN-COMP-PAT, and DOWN-PORT-PAT are globbing
120 patterns where only the wildcard character, *, is special: it matches
121 zero or more characters. You must escape the *, ?, [, ., :, and \
122 characters with \.
123
124 When you do not specify UP-PORT-PAT or DOWN-PORT-PAT, they are
125 equivalent to *.
126
127 You can leverage this connection mechanism to specify fallbacks with a
128 careful use of wildcards, as the order of the --connect options on the
129 command line is significant. For example:
130
131 --connect='A.out*:B.in*' --connect=A:B --connect='*:C'
132
133 With those connection rules, the run command connects:
134
135 • Any output port of which the name starts with out of component A to
136 the first input port of which the name starts with in of component
137 B.
138
139 • Any other output port of component A to the first available input
140 port of component B.
141
142 • Any other output port (of any component except A) to the first
143 available input port of component C.
144
145 The run command fails when it cannot find an input port to which to
146 connect a given output port using the provided connection rules.
147
148 See “EXAMPLES” for more examples.
149
151 General
152 You can use those options before the command name.
153
154 See babeltrace2(1) for more details.
155
156 -d, --debug
157 Legacy option: this is equivalent to --log-level=TRACE.
158
159 -l LVL, --log-level=LVL
160 Set the log level of all known Babeltrace 2 loggers to LVL.
161
162 --omit-home-plugin-path
163 Do not search for plugins in $HOME/.local/lib/babeltrace2/plugins.
164
165 --omit-system-plugin-path
166 Do not search for plugins in /usr/local/lib/babeltrace2/plugins.
167
168 --plugin-path=PATH[:PATH]...
169 Add PATH to the list of paths in which plugins can be found.
170
171 -v, --verbose
172 Legacy option: this is equivalent to --log-level=INFO.
173
174 Component creation
175 See “Create components” for more details.
176
177 -b PARAMS, --base-params=PARAMS
178 Set the current base parameters to PARAMS.
179
180 You can reset the current base parameters with the --reset-base-
181 params option.
182
183 See the --params option for the format of PARAMS.
184
185 -c NAME:COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME,
186 --component=NAME:COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME
187 Create a component named NAME from the component class of type
188 COMP-CLS-TYPE named COMP-CLS-NAME found in the plugin named
189 PLUGIN-NAME, and set it as the current component.
190
191 The available values for TYPE are:
192
193 source, src
194 Source component class.
195
196 filter, flt
197 Filter component class.
198
199 sink
200 Sink component class.
201
202 The initial initialization parameters of this component are copied
203 from the current base initialization parameters (see the --base-
204 params option).
205
206 -l LVL, --log-level=LVL
207 Set the log level of the current component to LVL.
208
209 The available values for LVL are:
210
211 NONE, N
212 Logging is disabled.
213
214 FATAL, F
215 Severe errors that lead the execution to abort immediately.
216
217 This level should be enabled in production.
218
219 ERROR, E
220 Errors that might still allow the execution to continue.
221
222 Usually, once one or more errors are reported at this level,
223 the application, plugin, or library won’t perform any more
224 useful task, but it should still exit cleanly.
225
226 This level should be enabled in production.
227
228 WARN, WARNING, W
229 Unexpected situations which still allow the execution to
230 continue.
231
232 This level should be enabled in production.
233
234 INFO, I
235 Informational messages that highlight progress or important
236 states of the application, plugins, or library.
237
238 This level can be enabled in production.
239
240 DEBUG, D
241 Debugging information, with a higher level of details than the
242 TRACE level.
243
244 This level should NOT be enabled in production.
245
246 TRACE, T
247 Low-level debugging context information.
248
249 This level should NOT be enabled in production.
250
251 -p PARAMS, --params=PARAMS
252 Add PARAMS to the initialization parameters of the current
253 component.
254
255 If PARAMS contains a key which exists in the current component’s
256 initialization parameters, replace the parameter.
257
258 The format of PARAMS is a comma-separated list of NAME=VALUE
259 assignments:
260
261 NAME=VALUE[,NAME=VALUE]...
262
263 NAME
264 Parameter name (C identifier plus the :, ., and - characters).
265
266 VALUE
267 One of:
268
269 • null, nul, NULL: null value.
270
271 • true, TRUE, yes, YES: true boolean value.
272
273 • false, FALSE, no, NO: false boolean value.
274
275 • Binary (0b prefix), octal (0 prefix), decimal, or
276 hexadecimal (0x prefix) unsigned (with + prefix) or signed
277 64-bit integer.
278
279 • Double precision floating point number (scientific notation
280 is accepted).
281
282 • Unquoted string with no special characters, and not
283 matching any of the null and boolean value symbols above.
284
285 • Double-quoted string (accepts escape characters).
286
287 • Array, formatted as an opening [, a comma-separated list of
288 VALUE, and a closing ].
289
290 • Map, formatted as an opening {, a comma-separated list of
291 NAME=VALUE assignments, and a closing }.
292
293 You may put whitespaces around the individual = (assignment), ,
294 (separator), [ (array beginning), ] (array end), { (map
295 beginning), and } (map end) characters.
296
297 Example:
298
299 --params='many=null, fresh=yes, condition=false, squirrel=-782329,
300 play=+23, observe=3.14, simple=beef,
301 needs-quotes="some string",
302 escape.chars-are:allowed="a \" quote",
303 things=[1, "hello", 2.71828],
304 frog={slow=2, bath=[bike, 23], blind=NO}'
305
306 Important
307 Like in the example above, make sure to single-quote the whole
308 argument when you run this command from a shell, as it can
309 contain many special characters.
310
311 -r, --reset-base-params
312 Reset the current base parameters.
313
314 You can set the current base parameters with the --base-params
315 option.
316
317 Component connection
318 -x CONN-RULE, --connect=CONN-RULE
319 Add the connection rule CONN-RULE.
320
321 The format of CONN-RULE is:
322
323 UP-COMP-PAT[.UP-PORT-PAT]:DOWN-COMP-PAT[.DOWN-PORT-PAT]
324
325 UP-COMP-PAT
326 Upstream component name pattern.
327
328 UP-PORT-PAT
329 Upstream (output) port name pattern.
330
331 DOWN-COMP-PAT
332 Downstream component name pattern.
333
334 DOWN-PORT-PAT
335 Downstream (input) port name pattern.
336
337 See “Connect components” to learn more.
338
339 Graph configuration
340 --retry-duration=TIME-US
341 Set the duration of a single retry to TIME-US µs when a sink
342 component reports "try again later" (busy network or file system,
343 for example).
344
345 Default: 100000 (100 ms).
346
347 Command information
348 -h, --help
349 Show the command’s help and quit.
350
352 Example 1. Create a single-port source component and a single-port sink
353 component and connect them.
354
355 $ babeltrace2 run --component=A:src.plug.my-src \
356 --component=B:sink.plug.my-sink \
357 --connect=A:B
358
359 Possible resulting graph:
360
361 +-----------------+ +-------------------+
362 | src.plug.my-src | | sink.plug.my-sink |
363 | [A] | | [B] |
364 | | | |
365 | out @--->@ in |
366 +-----------------+ +-------------------+
367
368 Example 2. Use the --params option to set the current component’s
369 initialization parameters.
370
371 In this example, the --params option only applies to component the-
372 source.
373
374 $ babeltrace2 run --component=the-source:src.my-plugin.my-src \
375 --params=offset=123,flag=true \
376 --component=the-sink:sink.my-plugin.my-sink \
377 --connect=the-source:the-sink
378
379 Example 3. Use the --base-params and --reset-base-params options to set
380 and reset the current base initialization parameters.
381
382 In this example, the effective initialization parameters of the created
383 components are:
384
385 Component A
386 offset=1203, flag=false
387
388 Component B
389 offset=1203, flag=true, type=event
390
391 Component C
392 ratio=0.25
393
394 $ babeltrace2 run --base-params=offset=1203,flag=false \
395 --component=A:src.plugin.compcls \
396 --component=B:flt.plugin.compcls \
397 --params=flag=true,type=event \
398 --reset-base-params \
399 --component=C:sink.plugin.compcls \
400 --params=ratio=0.25 \
401 --connect=A:B --connect=B:C
402
403 Example 4. Specify a component connection fallback rule.
404
405 In this example, any A output port of which the name starts with foo is
406 connected to a B input port of which the name starts with nin. Any
407 other A output port is connected to a B input port of which the name
408 starts with oth.
409
410 The order of the --connect options is important here: the opposite
411 order would create a system in which the first rule is always
412 satisfied, and any A output port, whatever its name, would be connected
413 to a B input port with a name that starts with oth.
414
415 $ babeltrace2 run --component=A:src.plug.my-src \
416 --component=B:sink.plug.my-sink \
417 --connect='A.foo*:B:nin*' --connect='A:B.oth*'
418
419 Possible resulting graph:
420
421 +-----------------+ +-------------------+
422 | src.plug.my-src | | sink.plug.my-sink |
423 | [A] | | [B] |
424 | | | |
425 | foot @--->@ nine |
426 | foodies @--->@ ninja |
427 | some-port @--->@ othello |
428 | hello @--->@ other |
429 +-----------------+ +-------------------+
430
432 Babeltrace 2 library
433 BABELTRACE_EXEC_ON_ABORT=CMDLINE
434 Execute the command line CMDLINE, as parsed like a UNIX 98 shell,
435 when any part of the Babeltrace 2 project unexpectedly aborts.
436
437 The application only aborts when the executed command returns,
438 ignoring its exit status.
439
440 This environment variable is ignored when the application has the
441 setuid or the setgid access right flag set.
442
443 BABELTRACE_TERM_COLOR=(AUTO | NEVER | ALWAYS)
444 Force the terminal color support for the babeltrace2(1) program and
445 the project’s plugins.
446
447 The available values are:
448
449 AUTO
450 Only emit terminal color codes when the standard output and
451 error streams are connected to a color-capable terminal.
452
453 NEVER
454 Never emit terminal color codes.
455
456 ALWAYS
457 Always emit terminal color codes.
458
459 BABELTRACE_TERM_COLOR_BRIGHT_MEANS_BOLD=0
460 Set to 0 to emit SGR (see
461 <https://en.wikipedia.org/wiki/ANSI_escape_code>) codes 90 to 97
462 for bright colors instead of bold (SGR code 1) and standard color
463 codes (SGR codes 30 to 37).
464
465 BABELTRACE_PLUGIN_PATH=PATHS
466 Set the list of directories, in order, in which dynamic plugins can
467 be found before other directories are considered to PATHS
468 (colon-separated, or semicolon on Windows).
469
470 LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS=1
471 Disable the loading of any Babeltrace 2 Python plugin.
472
473 LIBBABELTRACE2_INIT_LOG_LEVEL=LVL
474 Force the Babeltrace 2 library’s initial log level to be LVL.
475
476 If this environment variable is set, it overrides the log level set
477 by the --log-level option for the Babeltrace 2 library logger.
478
479 The available values for LVL are:
480
481 NONE, N
482 Logging is disabled.
483
484 FATAL, F
485 Severe errors that lead the execution to abort immediately.
486
487 This level should be enabled in production.
488
489 ERROR, E
490 Errors that might still allow the execution to continue.
491
492 Usually, once one or more errors are reported at this level,
493 the application, plugin, or library won’t perform any more
494 useful task, but it should still exit cleanly.
495
496 This level should be enabled in production.
497
498 WARN, WARNING, W
499 Unexpected situations which still allow the execution to
500 continue.
501
502 This level should be enabled in production.
503
504 INFO, I
505 Informational messages that highlight progress or important
506 states of the application, plugins, or library.
507
508 This level can be enabled in production.
509
510 DEBUG, D
511 Debugging information, with a higher level of details than the
512 TRACE level.
513
514 This level should NOT be enabled in production.
515
516 TRACE, T
517 Low-level debugging context information.
518
519 This level should NOT be enabled in production.
520
521 LIBBABELTRACE2_NO_DLCLOSE=1
522 Make the Babeltrace 2 library leave any dynamically loaded modules
523 (plugins and plugin providers) open at exit. This can be useful for
524 debugging purposes.
525
526 LIBBABELTRACE2_PLUGIN_PROVIDER_DIR=DIR
527 Set the directory from which the Babeltrace 2 library dynamically
528 loads plugin provider shared objects to DIR.
529
530 If this environment variable is set, it overrides the default
531 plugin provider directory.
532
533 Babeltrace 2 Python bindings
534 BABELTRACE_PYTHON_BT2_LOG_LEVEL=LVL
535 Force the Babeltrace 2 Python bindings log level to be LVL.
536
537 If this environment variable is set, it overrides the log level set
538 by the --log-level option for the Python bindings logger.
539
540 The available values for LVL are:
541
542 NONE, N
543 Logging is disabled.
544
545 FATAL, F
546 Severe errors that lead the execution to abort immediately.
547
548 This level should be enabled in production.
549
550 ERROR, E
551 Errors that might still allow the execution to continue.
552
553 Usually, once one or more errors are reported at this level,
554 the application, plugin, or library won’t perform any more
555 useful task, but it should still exit cleanly.
556
557 This level should be enabled in production.
558
559 WARN, WARNING, W
560 Unexpected situations which still allow the execution to
561 continue.
562
563 This level should be enabled in production.
564
565 INFO, I
566 Informational messages that highlight progress or important
567 states of the application, plugins, or library.
568
569 This level can be enabled in production.
570
571 DEBUG, D
572 Debugging information, with a higher level of details than the
573 TRACE level.
574
575 This level should NOT be enabled in production.
576
577 TRACE, T
578 Low-level debugging context information.
579
580 This level should NOT be enabled in production.
581
582 CLI
583 BABELTRACE_CLI_LOG_LEVEL=LVL
584 Force babeltrace2 CLI’s log level to be LVL.
585
586 If this environment variable is set, it overrides the log level set
587 by the --log-level option for the CLI logger.
588
589 The available values for LVL are:
590
591 NONE, N
592 Logging is disabled.
593
594 FATAL, F
595 Severe errors that lead the execution to abort immediately.
596
597 This level should be enabled in production.
598
599 ERROR, E
600 Errors that might still allow the execution to continue.
601
602 Usually, once one or more errors are reported at this level,
603 the application, plugin, or library won’t perform any more
604 useful task, but it should still exit cleanly.
605
606 This level should be enabled in production.
607
608 WARN, WARNING, W
609 Unexpected situations which still allow the execution to
610 continue.
611
612 This level should be enabled in production.
613
614 INFO, I
615 Informational messages that highlight progress or important
616 states of the application, plugins, or library.
617
618 This level can be enabled in production.
619
620 DEBUG, D
621 Debugging information, with a higher level of details than the
622 TRACE level.
623
624 This level should NOT be enabled in production.
625
626 TRACE, T
627 Low-level debugging context information.
628
629 This level should NOT be enabled in production.
630
631 BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH=0
632 Disable the warning message which babeltrace2-convert(1) prints
633 when you convert a trace with a relative path that’s also the name
634 of a babeltrace2 command.
635
636 BABELTRACE_DEBUG=1
637 Legacy variable: equivalent to setting the --log-level option to
638 TRACE.
639
640 BABELTRACE_VERBOSE=1
641 Legacy variable: equivalent to setting the --log-level option to
642 INFO.
643
645 $HOME/.local/lib/babeltrace2/plugins
646 User plugin directory.
647
648 /usr/local/lib/babeltrace2/plugins
649 System plugin directory.
650
651 /usr/local/lib/babeltrace2/plugin-providers
652 System plugin provider directory.
653
655 0 on success, 1 otherwise.
656
658 If you encounter any issue or usability problem, please report it on
659 the Babeltrace bug tracker (see
660 <https://bugs.lttng.org/projects/babeltrace>).
661
663 The Babeltrace project shares some communication channels with the
664 LTTng project (see <https://lttng.org/>).
665
666 • Babeltrace website (see <https://babeltrace.org/>)
667
668 • Mailing list (see <https://lists.lttng.org>) for support and
669 development: lttng-dev@lists.lttng.org
670
671 • IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
672 irc.oftc.net
673
674 • Bug tracker (see <https://bugs.lttng.org/projects/babeltrace>)
675
676 • Git repository (see <https://git.efficios.com/?p=babeltrace.git>)
677
678 • GitHub project (see <https://github.com/efficios/babeltrace>)
679
680 • Continuous integration (see
681 <https://ci.lttng.org/view/Babeltrace/>)
682
683 • Code review (see <https://review.lttng.org/q/project:babeltrace>)
684
686 The Babeltrace 2 project is the result of hard work by many regular
687 developers and occasional contributors.
688
689 The current project maintainer is Jérémie Galarneau
690 <mailto:jeremie.galarneau@efficios.com>.
691
693 This command is part of the Babeltrace 2 project.
694
695 Babeltrace is distributed under the MIT license (see
696 <https://opensource.org/licenses/MIT>).
697
699 babeltrace2-intro(7), babeltrace2(1), babeltrace2-convert(1)
700
701
702
703Babeltrace 2.0.4 14 September 2019 BABELTRACE2-RUN(1)