doc/man/babeltrace-run.1.txt

   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
  96 opt:--key='KEY' followed with opt:--value='VALUE'::
  97     Set the current component's initialization parameter named 'KEY' to
  98     the string value 'VALUE'. If 'KEY' exists in the current component's
  99     initialization parameters, the parameter is replaced.
 100
 101
 102 [[connect-comps]]
 103 Connect components
 104 ~~~~~~~~~~~~~~~~~~
 105 The components which you create from component classes with the
 106 opt:--component option (see <<create-comps,Create components>>) can
 107 create input and output _ports_ depending on their type. An output port
 108 is where notifications, like trace events, are sent. An input port is
 109 where notifications are received. For a given component instance, each
 110 port has a unique name.
 111
 112 The purpose of the `run` command is to create a trace processing graph,
 113 that is, to know which component ports to connect together. The command
 114 achieves this with the help of the connection rules that you provide
 115 with the opt:--connect option.
 116
 117 The format of a connection rule (the argument of the opt:--connect
 118 option) is:
 119
 120 [verse]
 121 __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
 122
 123 'UP-COMP-PATH'::
 124     Upstream component name pattern.
 125
 126 'UP-PORT-PAT'::
 127     Upstream port name pattern.
 128
 129 'DOWN-COMP-PATH'::
 130     Downstream component name pattern.
 131
 132 'DOWN-PORT-PAT'::
 133     Downstream port name pattern.
 134
 135 When a source or filter component adds a new output port within the
 136 processing graph, the `run` command does the following to find an
 137 input port to connect it to:
 138
 139 ----
 140 For each connection rule:
 141   If the output port's component's name matches UP-COMP-PAT and
 142   the output port's name matches UP-PORT-PAT:
 143     For each component COMP in the processing graph:
 144       If the name of COMP matches DOWN-COMP-PAT:
 145         Select the first input port of COMP of which the name
 146         matches DOWN-PORT-PAT, or fail with no match.
 147 Fail with no match.
 148 ----
 149
 150 __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
 151 __DOWN-PORT-PAT__ are globbing patterns where only the wildcard
 152 character, `*`, is special: it matches zero or more characters. You must
 153 escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:.
 154
 155 When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are
 156 equivalent to `*`.
 157
 158 You can leverage this connection mechanism to specify fallbacks with a
 159 careful use of wildcards. For example:
 160
 161 ----
 162 --connect='A.out*:B.in*' --connect=A:B --connect='*:C'
 163 ----
 164
 165 With those connection rules:
 166
 167 * Any output port of which the name starts with `out` of component `A`
 168   is connected to the first input port of which the name starts with
 169   `in` of component `B`.
 170
 171 * Any other output port of component `A` is connected to the first
 172   available input port of component `B`.
 173
 174 * Any other output port (of any component except `A`) is connected to
 175   the first available input port of component `C`.
 176
 177 The `run` command fails when it cannot find an input port to which to
 178 connect a created output port using the provided connection
 179 rules.
 180
 181 See <<examples,EXAMPLES>> for more examples.
 182
 183
 184 include::common-cmd-params-format.txt[]
 185
 186 include::common-cmd-plugin-path.txt[]
 187
 188
 189 OPTIONS
 190 -------
 191 include::common-gen-options.txt[]
 192
 193
 194 Component creation
 195 ~~~~~~~~~~~~~~~~~~
 196 opt:-b 'PARAMS', opt:--base-params='PARAMS'::
 197     Set the current base parameters to 'PARAMS'. You can reset the
 198     current base parameters with the opt:--reset-base-params option.
 199     See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
 200
 201 opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
 202     Create a component initially named 'NAME' (if specified) from the
 203     component class of type 'TYPE' named 'COMPCLS' found in the plugin
 204     named 'PLUGIN', and set it as the current component.
 205 +
 206 The available values for 'TYPE' are:
 207 +
 208 --
 209 `source`::
 210 `src`::
 211     Source component class.
 212
 213 `filter`::
 214 `flt`::
 215     Filter component class.
 216
 217 `sink`::
 218     Sink component class.
 219 --
 220 +
 221 The initial initialization parameters of this component are copied from
 222 the current base initialization parameters (see the opt:--base-params
 223 option).
 224
 225 opt:--key='KEY'::
 226     Set the current parameter key to 'KEY'. The next opt:--value option
 227     uses this key to add a parameter to the current component.
 228
 229 opt:--name='NAME'::
 230     Set the name of the current component to 'NAME'. The names of all
 231     the components in the processing graph must be unique.
 232
 233 opt:-p 'PARAMS', opt:--params='PARAMS'::
 234     Add 'PARAMS' to the initialization parameters of the current
 235     component. If 'PARAMS' contains a key which exists in the current
 236     component's initialization parameters, replace the parameter.
 237     See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
 238
 239 opt:-r, opt:--reset-base-params::
 240     Reset the current base parameters. You can set the current base
 241     parameters with the opt:--base-params option.
 242
 243 opt:-v 'VALUE', opt:--value='VALUE'::
 244     Add a parameter to the current component's initialization parameters
 245     of which the key is the argument of the last opt:--key option and
 246     the string value is 'VALUE'. If the current component's
 247     initialization parameters already contain a key named 'KEY', replace
 248     the parameter.
 249
 250
 251 Component connection
 252 ~~~~~~~~~~~~~~~~~~~~
 253 opt:-C 'CONN-RULE', opt:--connect='CONN-RULE'::
 254     Add the connection rule 'CONN-RULE'. See
 255     <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
 256
 257
 258 Graph configuration
 259 ~~~~~~~~~~~~~~~~~~~
 260 opt:--retry-duration='DURUS'::
 261     Set the duration of a single retry to 'DURUS'{nbsp}µs when a
 262     component reports "try again later" (busy network or file system,
 263     for example).
 264 +
 265 Default: 100000 (100{nbsp}ms).
 266
 267
 268 include::common-plugin-path-options.txt[]
 269
 270 include::common-cmd-info-options.txt[]
 271
 272
 273 [[examples]]
 274 EXAMPLES
 275 --------
 276 .Create a single-port source component and a single-port sink component and connect them.
 277 ====
 278 [role="term"]
 279 ----
 280 $ babeltrace run --component=A:src.plug.my-src \
 281                  --component=B:sink.plug.my-sink \
 282                  --connect=A:B
 283 ----
 284
 285 Possible resulting graph:
 286
 287 ----
 288 +-----------------+    +-------------------+
 289 | src.plug.my-src |    | sink.plug.my-sink |
 290 |       [A]       |    |         [B]       |
 291 |                 |    |                   |
 292 |             out @--->@ in                |
 293 +-----------------+    +-------------------+
 294 ----
 295 ====
 296
 297 .Use the opt:--name option to name the current component.
 298 ====
 299 [role="term"]
 300 ----
 301 $ babeltrace run --component=src.plug.my-src --name=the-source \
 302                  --component=the-sink:sink.plug.my-sink \
 303                  --connect=the-source:the-sink
 304 ----
 305 ====
 306
 307 .Use the opt:--params option to set the current component's initialization parameters.
 308 ====
 309 In this example, the opt:--params option only applies to component
 310 `the-source`.
 311
 312 [role="term"]
 313 ----
 314 $ babeltrace run --component=the-source:src.my-plugin.my-src \
 315                  --params='offset=123, flag=true' \
 316                  --component=the-sink:sink.my-plugin.my-sink \
 317                  --connect=the-source:the-sink
 318 ----
 319 ====
 320
 321 .Use the opt:--key and opt:--value options to set a current component's initialization parameter.
 322 ====
 323 [role="term"]
 324 ----
 325 $ babeltrace run --component=the-source:src.my-plugin.my-src \
 326                  --key=path --value ~/my-traces/the-trace
 327                  --component=the-sink:sink.my-plugin.my-sink \
 328                  --connect=the-source:the-sink
 329 ----
 330 ====
 331
 332 .Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters.
 333 ====
 334 In this example, the effective initialization parameters of the
 335 created components are:
 336
 337 * Component `A`: `offset=1203, flag=false`
 338 * Component `B`: `offset=1203, flag=true, type=event`
 339 * Component `C`: `ratio=0.25`
 340
 341 [role="term"]
 342 ----
 343 $ babeltrace run --base-params='offset=1203, flag=false' \
 344                  --component=A:src.plugin.compcls \
 345                  --component=B:flt.plugin.compcls \
 346                  --params='flag=true, type=event' \
 347                  --reset-base-params \
 348                  --component=C:sink.plugin.compcls \
 349                  --params='ratio=0.25' \
 350                  --connect=A:B --connect=B:C
 351 ----
 352 ====
 353
 354 .Specify a component connection fallback rule.
 355 ====
 356 In this example, any `A` output port of which the name starts with
 357 `foo` is connected to a `B` input port of which the name starts with
 358 `nin`. Any other `A` output port is connected to a `B` input port of
 359 which the name starts with `oth`.
 360
 361 The order of the opt:--connect options is important here: the opposite
 362 order would create a system in which the first rule is always satisfied,
 363 and _any_ `A` output port, whatever its name, would be connected to a
 364 `B` input port with a name that starts with `oth`.
 365
 366 [role="term"]
 367 ----
 368 $ babeltrace run --component=A:src.plug.my-src \
 369                  --component=B:sink.plug.my-sink \
 370                  --connect='A.foo*:B:nin*' --connect='A:B.oth*'
 371 ----
 372
 373 Possible resulting graph:
 374
 375 ----
 376 +-----------------+    +-------------------+
 377 | src.plug.my-src |    | sink.plug.my-sink |
 378 |       [A]       |    |        [B]        |
 379 |                 |    |                   |
 380 |            foot @--->@ nine              |
 381 |         foodies @--->@ ninja             |
 382 |       some-port @--->@ othello           |
 383 |           hello @--->@ other             |
 384 +-----------------+    +-------------------+
 385 ----
 386 ====
 387
 388
 389 include::common-cli-env.txt[]
 390
 391 include::common-cli-files.txt[]
 392
 393 include::common-cmd-footer.txt[]
 394
 395
 396 SEE ALSO
 397 --------
 398 man:babeltrace(1),
 399 man:babeltrace-convert(1),
 400 man:babeltrace-intro(7)