doc/man/babeltrace2-run.1.txt

   1 = babeltrace2-run(1)
   2 :manpagetype: command
   3 :revdate: 14 September 2019
   4
   5
   6 == NAME
   7
   8 babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it
   9
  10
  11 [[synopsis]]
  12 == SYNOPSIS
  13
  14 [verse]
  15 *babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *run* [opt:--retry-duration='TIME-US']
  16             opt:--connect='CONN-RULE'... 'COMPONENTS'
  17
  18
  19 == DESCRIPTION
  20
  21 The `run` command creates a Babeltrace~2 trace processing graph and
  22 runs it.
  23
  24 include::common-see-babeltrace2-intro.txt[]
  25
  26 The `run` command dynamically loads Babeltrace~2 plugins which
  27 supply component classes. With the `run` command, you specify which
  28 component classes to instantiate as components and how to connect them.
  29
  30 The steps to write a `babeltrace2 run` command line are:
  31
  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.
  37
  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.
  42
  43 NOTE: The man:babeltrace2-convert(1) command is a specialization of the
  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
  46 manopt:babeltrace2-convert(1):--run-args or
  47 manopt:babeltrace2-convert(1):--run-args-0 option to make it print the
  48 equivalent `run` command line instead.
  49
  50
  51 [[create-comps]]
  52 === Create components
  53
  54 To create a component, use the opt:--component option. This option
  55 specifies:
  56
  57 * The name of the component, unique amongst all the component names of
  58   the trace processing graph.
  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
  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.
  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
  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.
  86
  87
  88 [[connect-comps]]
  89 === Connect components
  90
  91 The components which you create from component classes with the
  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.
  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
 101 with one or more opt:--connect='CONN-RULE' options.
 102
 103 The format of 'CONN-RULE' is:
 104
 105 [verse]
 106 __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
 107
 108 'UP-COMP-PAT'::
 109     Upstream component name pattern.
 110
 111 'UP-PORT-PAT'::
 112     Upstream (output) port name pattern.
 113
 114 'DOWN-COMP-PAT'::
 115     Downstream component name pattern.
 116
 117 'DOWN-PORT-PAT'::
 118     Downstream (input) port name pattern.
 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 ----
 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:
 129       If the name of COMP matches DOWN-COMP-PAT:
 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.
 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
 145 careful use of wildcards, as the order of the opt:--connect options on
 146 the command line is significant. For example:
 147
 148 ----
 149 --connect='A.out*:B.in*' --connect=A:B --connect='*:C'
 150 ----
 151
 152 With those connection rules, the `run` command connects:
 153
 154 * Any output port of which the name starts with `out` of component `A`
 155   to the first input port of which the name starts with `in` of
 156   component `B`.
 157
 158 * Any other output port of component `A` to the first available input
 159   port of component `B`.
 160
 161 * Any other output port (of any component except `A`) to the first
 162   available input port of component `C`.
 163
 164 The `run` command fails when it cannot find an input port to which to
 165 connect a given output port using the provided connection rules.
 166
 167 See <<examples,``EXAMPLES''>> for more examples.
 168
 169
 170 == OPTIONS
 171
 172 include::common-gen-options.txt[]
 173
 174
 175 === Component creation
 176
 177 See <<create-comps,``Create components''>> for more details.
 178
 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'.
 187
 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.
 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
 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 --
 222
 223 opt:-p 'PARAMS'::
 224 opt:--params='PARAMS'::
 225     Add 'PARAMS' to the initialization parameters of the current
 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
 242
 243 === Component connection
 244
 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.
 269
 270
 271 === Graph configuration
 272
 273 opt:--retry-duration='TIME-US'::
 274     Set the duration of a single retry to 'TIME-US'~µs when a sink
 275     component reports "try again later" (busy network or file system,
 276     for example).
 277 +
 278 Default: 100000 (100~ms).
 279
 280
 281 include::common-cmd-info-options.txt[]
 282
 283
 284 [[examples]]
 285 == EXAMPLES
 286
 287 .Create a single-port source component and a single-port sink component and connect them.
 288 ====
 289 [role="term"]
 290 ----
 291 $ babeltrace2 run --component=A:src.plug.my-src \
 292                   --component=B:sink.plug.my-sink \
 293                   --connect=A:B
 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
 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 ----
 315 $ babeltrace2 run --component=the-source:src.my-plugin.my-src \
 316                   --params=offset=123,flag=true \
 317                   --component=the-sink:sink.my-plugin.my-sink \
 318                   --connect=the-source:the-sink
 319 ----
 320 ====
 321
 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
 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`
 335
 336 [role="term"]
 337 ----
 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
 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 ----
 363 $ babeltrace2 run --component=A:src.plug.my-src \
 364                   --component=B:sink.plug.my-sink \
 365                   --connect='A.foo*:B:nin*' --connect='A:B.oth*'
 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
 386
 387 include::common-cli-files.txt[]
 388
 389
 390 include::common-cmd-footer.txt[]
 391
 392
 393 == SEE ALSO
 394
 395 man:babeltrace2-intro(7),
 396 man:babeltrace2(1),
 397 man:babeltrace2-convert(1)