X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=doc%2Fman%2Fbabeltrace2-run.1.txt;h=4c376b789e40f9014889cd0f01f424d04c519e52;hb=e70712b34fcae860414660c6b10451f57b50c25d;hp=dcdd26b84873a12c11e32bf36aa89f89223e7feb;hpb=0713ec72ea9f82718c4d54324d6f80eec9c357e0;p=babeltrace.git diff --git a/doc/man/babeltrace2-run.1.txt b/doc/man/babeltrace2-run.1.txt index dcdd26b8..4c376b78 100644 --- a/doc/man/babeltrace2-run.1.txt +++ b/doc/man/babeltrace2-run.1.txt @@ -1,45 +1,44 @@ -babeltrace2-run(1) -================= += babeltrace2-run(1) :manpagetype: command -:revdate: 5 October 2017 +:revdate: 14 September 2019 -NAME ----- -babeltrace2-run - Create a trace processing graph and run it +== NAME + +babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it -SYNOPSIS --------- +[[synopsis]] +== SYNOPSIS + [verse] -*babeltrace2 run* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path] - [opt:--omit-system-plugin-path] - [opt:--plugin-path='PATH'[:__PATH__]...] - [opt:--retry-duration='DURUS'] - opt:--connect='CONN-RULE'... 'COMPONENTS' +*babeltrace2* [<>] *run* [opt:--retry-duration='TIME-US'] + opt:--connect='CONN-RULE'... 'COMPONENTS' + +== DESCRIPTION -DESCRIPTION ------------ -The `run` command creates a trace processing graph and runs it. +The `run` command creates a Babeltrace~2 trace processing graph and +runs it. -See man:babeltrace2-intro(7) to learn more about the Babeltrace -project and its core concepts. +include::common-see-babeltrace2-intro.txt[] -The `run` command uses libbabeltrace2 to dynamically load plugins which +The `run` command dynamically loads Babeltrace~2 plugins which supply component classes. With the `run` command, you specify which -component classes to instantiate as components and how they must be -connected. +component classes to instantiate as components and how to connect them. The steps to write a `babeltrace2 run` command line are: -. Specify which component classes to instantiate as components and - how. This is the 'COMPONENTS' part of the synopsis. See - <> to learn more. +. Specify which component classes to instantiate as components with many + opt:--component options and how to configure them. ++ +This is the 'COMPONENTS' part of the <>. See +<> to learn more. -. Specify how to connect component instances together with one or more - opt:--connect options. See <> to - learn more. +. Specify how to connect components together with one or more + opt:--connect options. ++ +See <> to learn more. NOTE: The man:babeltrace2-convert(1) command is a specialization of the `run` command for the very common case of converting one or more traces: @@ -50,13 +49,13 @@ equivalent `run` command line instead. [[create-comps]] -Create components -~~~~~~~~~~~~~~~~~ +=== Create components + To create a component, use the opt:--component option. This option specifies: -* **Optional**: The name of the component instance. You can also use the - opt:--name option for this. +* The name of the component, unique amongst all the component names of + the trace processing graph. * The type of the component class to instantiate: source, filter, or sink. @@ -66,9 +65,9 @@ specifies: * The name of the component class to instantiate. -You can use the opt:--component option multiple times to create -multiple components. You can instantiate the same component class -multiple times as different component instances. +Use the opt:--component option multiple times to create multiple +components. You can instantiate the same component class multiple times +as different components. At any point in the command line, the opt:--base-params sets the current base initialization parameters and the opt:--reset-base-params resets @@ -80,66 +79,58 @@ Immediately following a opt:--component option on the command line, the created component is known as the _current component_ (until the next opt:--component option). -The following, optional command-line options apply to the current -component: - -opt:--name='NAME':: - Set the name of the current component to 'NAME'. - -opt:--params='PARAMS':: - Add 'PARAMS' to the initialization parameters of the current - component. If 'PARAMS' contains a key which exists in the current - component's initialization parameters, this parameter is replaced. -+ -See <> for the format of 'PARAMS'. +The opt:--params='PARAMS' option adds parameters to the current +component's initialization parameters. If 'PARAMS' contains a key which +exists in the current component's initialization parameters, this +parameter is replaced. [[connect-comps]] -Connect components -~~~~~~~~~~~~~~~~~~ +=== Connect components + The components which you create from component classes with the -opt:--component option (see <>) can -create input and output _ports_ depending on their type. An output port -is where notifications, like trace events, are sent. An input port is -where notifications are received. For a given component instance, each -port has a unique name. +opt:--component option (see <>) add +input and output _ports_ depending on their type. An output port is from +where messages, like trace events, are sent. An input port is where +messages are received. For a given component, each port has a unique +name. The purpose of the `run` command is to create a trace processing graph, that is, to know which component ports to connect together. The command achieves this with the help of the connection rules that you provide -with the opt:--connect option. +with one or more opt:--connect='CONN-RULE' options. -The format of a connection rule (the argument of the opt:--connect -option) is: +The format of 'CONN-RULE' is: [verse] __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] -'UP-COMP-PATH':: +'UP-COMP-PAT':: Upstream component name pattern. 'UP-PORT-PAT':: - Upstream port name pattern. + Upstream (output) port name pattern. -'DOWN-COMP-PATH':: +'DOWN-COMP-PAT':: Downstream component name pattern. 'DOWN-PORT-PAT':: - Downstream port name pattern. + Downstream (input) port name pattern. When a source or filter component adds a new output port within the processing graph, the `run` command does the following to find an input port to connect it to: ---- -For each connection rule: - If the output port's component's name matches UP-COMP-PAT and - the output port's name matches UP-PORT-PAT: - For each component COMP in the processing graph: +For each connection rule (--connect options, in order): + If the output port's component's name matches UP-COMP-PAT and the + output port's name matches UP-PORT-PAT: + For each component COMP in the trace processing graph: If the name of COMP matches DOWN-COMP-PAT: - Select the first input port of COMP of which the name - matches DOWN-PORT-PAT, or fail with no match. -Fail with no match. + Select the first input port of COMP of which the name matches + DOWN-PORT-PAT, or fail with no match. + +No possible connection: fail with no match. ---- __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and @@ -151,52 +142,54 @@ When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are equivalent to `*`. You can leverage this connection mechanism to specify fallbacks with a -careful use of wildcards. For example: +careful use of wildcards, as the order of the opt:--connect options on +the command line is significant. For example: ---- --connect='A.out*:B.in*' --connect=A:B --connect='*:C' ---- -With those connection rules: +With those connection rules, the `run` command connects: * Any output port of which the name starts with `out` of component `A` - is connected to the first input port of which the name starts with - `in` of component `B`. + to the first input port of which the name starts with `in` of + component `B`. -* Any other output port of component `A` is connected to the first - available input port of component `B`. +* Any other output port of component `A` to the first available input + port of component `B`. -* Any other output port (of any component except `A`) is connected to - the first available input port of component `C`. +* Any other output port (of any component except `A`) to the first + available input port of component `C`. The `run` command fails when it cannot find an input port to which to -connect a created output port using the provided connection -rules. +connect a given output port using the provided connection rules. -See <> for more examples. +See <> for more examples. -include::common-cmd-params-format.txt[] +== OPTIONS -include::common-cmd-plugin-path.txt[] +include::common-gen-options.txt[] -OPTIONS -------- -include::common-gen-options.txt[] +=== Component creation +See <> for more details. -Component creation -~~~~~~~~~~~~~~~~~~ -opt:-b 'PARAMS', opt:--base-params='PARAMS':: - Set the current base parameters to 'PARAMS'. You can reset the - current base parameters with the opt:--reset-base-params option. - See <> for the format of 'PARAMS'. +opt:-b 'PARAMS':: +opt:--base-params='PARAMS':: + Set the current base parameters to 'PARAMS'. ++ +You can reset the current base parameters with the +opt:--reset-base-params option. ++ +See the opt:--params option for the format of 'PARAMS'. -opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS':: - Create a component initially named 'NAME' (if specified) from the - component class of type 'TYPE' named 'COMPCLS' found in the plugin - named 'PLUGIN', and set it as the current component. +opt:-c __NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME':: +opt:--component=__NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME':: + Create a component named 'NAME' from the component class of type + 'COMP-CLS-TYPE' named 'COMP-CLS-NAME' found in the plugin named + 'PLUGIN-NAME', and set it as the current component. + The available values for 'TYPE' are: + @@ -217,53 +210,87 @@ The initial initialization parameters of this component are copied from the current base initialization parameters (see the opt:--base-params option). -opt:--name='NAME':: - Set the name of the current component to 'NAME'. The names of all - the components in the processing graph must be unique. +opt:-l 'LVL':: +opt:--log-level='LVL':: + Set the log level of the current component to 'LVL'. ++ +The available values for 'LVL' are: ++ +-- +include::common-log-levels.txt[] +-- -opt:-p 'PARAMS', opt:--params='PARAMS':: +opt:-p 'PARAMS':: +opt:--params='PARAMS':: Add 'PARAMS' to the initialization parameters of the current - component. If 'PARAMS' contains a key which exists in the current - component's initialization parameters, replace the parameter. - See <> for the format of 'PARAMS'. + component. ++ +If 'PARAMS' contains a key which exists in the current component's +initialization parameters, replace the parameter. ++ +-- +include::common-cmd-params-format.txt[] +-- + +opt:-r:: +opt:--reset-base-params:: + Reset the current base parameters. ++ +You can set the current base parameters with the opt:--base-params +option. + -opt:-r, opt:--reset-base-params:: - Reset the current base parameters. You can set the current base - parameters with the opt:--base-params option. +=== Component connection +opt:-x 'CONN-RULE':: +opt:--connect='CONN-RULE':: + Add the connection rule 'CONN-RULE'. ++ +The format of 'CONN-RULE' is: ++ +[verse] +__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] ++ +-- +'UP-COMP-PAT':: + Upstream component name pattern. + +'UP-PORT-PAT':: + Upstream (output) port name pattern. + +'DOWN-COMP-PAT':: + Downstream component name pattern. + +'DOWN-PORT-PAT':: + Downstream (input) port name pattern. +-- ++ +See <> to learn more. -Component connection -~~~~~~~~~~~~~~~~~~~~ -opt:-x 'CONN-RULE', opt:--connect='CONN-RULE':: - Add the connection rule 'CONN-RULE'. See - <> for the format of 'CONN-RULE'. +=== Graph configuration -Graph configuration -~~~~~~~~~~~~~~~~~~~ -opt:--retry-duration='DURUS':: - Set the duration of a single retry to 'DURUS'{nbsp}µs when a +opt:--retry-duration='TIME-US':: + Set the duration of a single retry to 'TIME-US'~µs when a sink component reports "try again later" (busy network or file system, for example). + -Default: 100000 (100{nbsp}ms). +Default: 100000 (100~ms). -include::common-plugin-path-options.txt[] - include::common-cmd-info-options.txt[] [[examples]] -EXAMPLES --------- +== EXAMPLES + .Create a single-port source component and a single-port sink component and connect them. ==== [role="term"] ---- $ babeltrace2 run --component=A:src.plug.my-src \ - --component=B:sink.plug.my-sink \ - --connect=A:B + --component=B:sink.plug.my-sink \ + --connect=A:B ---- Possible resulting graph: @@ -278,16 +305,6 @@ Possible resulting graph: ---- ==== -.Use the opt:--name option to name the current component. -==== -[role="term"] ----- -$ babeltrace2 run --component=src.plug.my-src --name=the-source \ - --component=the-sink:sink.plug.my-sink \ - --connect=the-source:the-sink ----- -==== - .Use the opt:--params option to set the current component's initialization parameters. ==== In this example, the opt:--params option only applies to component @@ -296,9 +313,9 @@ In this example, the opt:--params option only applies to component [role="term"] ---- $ babeltrace2 run --component=the-source:src.my-plugin.my-src \ - --params='offset=123, flag=true' \ - --component=the-sink:sink.my-plugin.my-sink \ - --connect=the-source:the-sink + --params=offset=123,flag=true \ + --component=the-sink:sink.my-plugin.my-sink \ + --connect=the-source:the-sink ---- ==== @@ -307,20 +324,25 @@ $ babeltrace2 run --component=the-source:src.my-plugin.my-src \ In this example, the effective initialization parameters of the created components are: -* Component `A`: `offset=1203, flag=false` -* Component `B`: `offset=1203, flag=true, type=event` -* Component `C`: `ratio=0.25` +Component `A`:: + `offset=1203, flag=false` + +Component `B`:: + `offset=1203, flag=true, type=event` + +Component `C`:: + `ratio=0.25` [role="term"] ---- -$ babeltrace2 run --base-params='offset=1203, flag=false' \ - --component=A:src.plugin.compcls \ - --component=B:flt.plugin.compcls \ - --params='flag=true, type=event' \ - --reset-base-params \ - --component=C:sink.plugin.compcls \ - --params='ratio=0.25' \ - --connect=A:B --connect=B:C +$ babeltrace2 run --base-params=offset=1203,flag=false \ + --component=A:src.plugin.compcls \ + --component=B:flt.plugin.compcls \ + --params=flag=true,type=event \ + --reset-base-params \ + --component=C:sink.plugin.compcls \ + --params=ratio=0.25 \ + --connect=A:B --connect=B:C ---- ==== @@ -339,8 +361,8 @@ and _any_ `A` output port, whatever its name, would be connected to a [role="term"] ---- $ babeltrace2 run --component=A:src.plug.my-src \ - --component=B:sink.plug.my-sink \ - --connect='A.foo*:B:nin*' --connect='A:B.oth*' + --component=B:sink.plug.my-sink \ + --connect='A.foo*:B:nin*' --connect='A:B.oth*' ---- Possible resulting graph: @@ -361,13 +383,15 @@ Possible resulting graph: include::common-cli-env.txt[] + include::common-cli-files.txt[] + include::common-cmd-footer.txt[] -SEE ALSO --------- +== SEE ALSO + +man:babeltrace2-intro(7), man:babeltrace2(1), -man:babeltrace2-convert(1), -man:babeltrace2-intro(7) +man:babeltrace2-convert(1)