doc/man/babeltrace2-run.1.txt

   1 babeltrace2-run(1)
   2 =================
   3 :manpagetype: command
   4 :revdate: 5 October 2017
   5
   6
   7 NAME
   8 ----
   9 babeltrace2-run - Create a trace processing graph and run it
  10
  11
  12 SYNOPSIS
  13 --------
  14 [verse]
  15 *babeltrace2 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:babeltrace2-intro(7) to learn more about the Babeltrace
  27 project and its core concepts.
  28
  29 The `run` command uses libbabeltrace2 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 `babeltrace2 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:babeltrace2-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:babeltrace2-convert(1):--run-args or
  48 manopt:babeltrace2-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
  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
 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
 234
 235 Component connection
 236 ~~~~~~~~~~~~~~~~~~~~
 237 opt:-x 'CONN-RULE', opt:--connect='CONN-RULE'::
 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 $ babeltrace2 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 $ babeltrace2 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 $ babeltrace2 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
 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 $ babeltrace2 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 $ babeltrace2 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:babeltrace2(1),
 372 man:babeltrace2-convert(1),
 373 man:babeltrace2-intro(7)