babeltrace2-run(1)

1BABELTRACE2-RUN(1)            Babeltrace 2 manual           BABELTRACE2-RUN(1)
2
3
4

NAME

6       babeltrace2-run - Create a Babeltrace 2 trace processing graph and run
7       it
8

SYNOPSIS

10       babeltrace2 [GENERAL OPTIONS] run [--retry-duration=TIME-US]
11                   --connect=CONN-RULE... COMPONENTS
12

DESCRIPTION

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

OPTIONS

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

EXAMPLES

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

ENVIRONMENT VARIABLES

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

FILES

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

EXIT STATUS

655       0 on success, 1 otherwise.
656

BUGS

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

RESOURCES

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

AUTHORS

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

COPYRIGHT

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