cpp-common/bt2: add C++ graph bindings

[babeltrace.git] / doc / man / babeltrace2-convert.1.txt

diff --git a/doc/man/babeltrace2-convert.1.txt b/doc/man/babeltrace2-convert.1.txt
index 1bf554f005108cae5b50f7fa5aa27d54bf759534..d20862a97a69b90b5949eeb3d50e3441f4c293a4 100644 (file)
--- a/doc/man/babeltrace2-convert.1.txt
+++ b/doc/man/babeltrace2-convert.1.txt
@@ -1,57 +1,61 @@
-babeltrace2-convert(1)
-=====================
+= babeltrace2-convert(1)

 :manpagetype: command
 :manpagetype: command

-:revdate: 5 October 2017
+:revdate: 14 September 2019

 
 
 
 

-NAME
-----
-babeltrace2-convert - Convert one or more traces
+== NAME
+
+babeltrace2-convert - Convert one or more traces to a given format
+
+
+== SYNOPSIS
+
+Pretty-print (plain text) the events, in order, of one or more traces:
+
+[verse]
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--retry-duration='TIME-US']
+            'TRACE-PATH'...

 
 

+Convert one or more traces to a given format:

 
 

-SYNOPSIS
---------
-Convert one or more traces:
+[verse]
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--retry-duration='TIME-US']
+            'CONVERSION ARGS'
+
+Get the equivalent man:babeltrace2-run(1) command arguments to convert
+one or more traces to a given format:

 
 [verse]
 
 [verse]

-*babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
-                   [opt:--omit-system-plugin-path]
-                   [opt:--plugin-path='PATH'[:__PATH__]...]
-                   [opt:--run-args | opt:--run-args-0] [opt:--retry-duration='DURUS']
-                   'CONVERSION ARGUMENTS'
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--retry-duration='TIME-US']
+            (opt:--run-args | opt:--run-args-0) 'CONVERSION ARGS'

 
 Print the metadata text of a CTF trace:
 
 [verse]
 
 Print the metadata text of a CTF trace:
 
 [verse]

-*babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
-                   [opt:--omit-system-plugin-path]
-                   [opt:--plugin-path='PATH'[:__PATH__]...]
-                   [opt:--output='OUTPATH']
-                   opt:--output-format=`ctf-metadata` 'TRACE-PATH'
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--output='OUTPATH']
+            opt:--output-format=`ctf-metadata` 'TRACE-PATH'

 
 

-Print the available http://lttng.org/docs/#doc-lttng-live[LTTng live]
-sessions:
+Print the available https://lttng.org/docs/#doc-lttng-live[remote LTTng
+tracing sessions]:

 
 [verse]
 
 [verse]

-*babeltrace2 convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
-                   [opt:--omit-system-plugin-path]
-                   [opt:--plugin-path='PATH'[:__PATH__]...]
-                   [opt:--output='OUTPATH'] opt:--input-format=`lttng-live` 'URL'
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] [*convert*] [opt:--output='OUTPATH']
+            opt:--input-format=`lttng-live` 'URL'

 
 
 
 

-DESCRIPTION
------------
-The `convert` command creates a trace conversion graph and runs it.
+== DESCRIPTION

 
 

-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+The `convert` command converts one or more traces to a given format,
+possibly with filters in the conversion path.
+
+include::common-see-babeltrace2-intro.txt[]

 
 [NOTE]
 ====
 
 [NOTE]
 ====

-`convert` is the default man:babeltrace2(1) command: you usually don't
-need to specify its name. The following commands are equivalent
-if the `...` part does not start with another man:babeltrace2(1)
-command's name, like `run` or `list-plugins`:
+`convert` is the default man:babeltrace2(1) command: you generally don't
+need to specify its name. The following commands are equivalent if the
+`...` part does not start with another man:babeltrace2(1) command's
+name, like `run` or `list-plugins`:

 
 [role="term"]
 ----
 
 [role="term"]
 ----


@@ -63,52 +67,69 @@ If you need to make sure that you are executing the `convert` command,
 use `babeltrace2 convert` explicitly.
 ====
 
 use `babeltrace2 convert` explicitly.
 ====
 

+More specifically, the `convert` command creates a conversion graph.
+

 A conversion graph is a specialized trace processing graph focused on
 the conversion of one or more traces to another format, possibly
 A conversion graph is a specialized trace processing graph focused on
 the conversion of one or more traces to another format, possibly

-filtering their events and other notifications in the process. A
-conversion graph is a linear chain of components after the source
-streams are merged:
+filtering or modifying their events and other messages in the process. A
+conversion graph is a linear chain of components once the source streams
+are merged:

 
 ----
 +----------+
 
 ----
 +----------+

-| source 1 |-.
+| source 1 @-.

 +----------+ |
              |  +-------+
 +----------+ |
              |  +-------+

-+----------+ '->|       |    +---------+    +------------+
-| source 2 |--->| muxer |--->| trimmer |--->| debug-info |-.
-+----------+ .->|       |    +---------+    +------------+ |
++----------+ '->@       |    +---------+    +------------+
+| source 2 @--->@ muxer @--->@ trimmer @--->@ debug-info @-.
++----------+ .->@       |    +---------+    +------------+ |

              |  +-------+                                  |
 +----------+ |    .----------------------------------------'
              |  +-------+                                  |
 +----------+ |    .----------------------------------------'

-|   ...    |-'    |  +---------------+    +------+
-+----------+      '->| other filters |--->| sink |
+|   ...    @-'    |  +---------------+    +------+
++----------+      '->@ other filters |--->@ sink |

                      +---------------+    +------+
 ----
 
 Note that the trimmer, debugging information, and other filters are
                      +---------------+    +------+
 ----
 
 Note that the trimmer, debugging information, and other filters are

-optional. See <<comp-create-impl,Create implicit components>> to learn
-how to enable them.
+optional. See <<comp-create-impl-opt,``Create implicit components from
+options''>> to learn how to enable them.

 
 

-If you need another processing graph layout, use the more flexible
+If you need another trace processing graph layout, use the more flexible

 man:babeltrace2-run(1) command.
 
 Like with the man:babeltrace2-run(1) command, you can create components
 explicitly with the opt:--component option (see
 man:babeltrace2-run(1) command.
 
 Like with the man:babeltrace2-run(1) command, you can create components
 explicitly with the opt:--component option (see

-<<comp-create-expl,Create explicit components>>). You can also use one
-of the many specific `convert` command options and arguments to create
-implicit components from known component classes (see
-<<comp-create-impl,Create implicit components>>). For example, you can
-specify a single path argument to print the merged events of a CTF trace
-on the console:
+<<comp-create-expl,``Create explicit components''>>). You can also use
+one of the many specific `convert` command options (see
+<<comp-create-impl-opt,``Create implicit components from options''>>)
+and non-option arguments (see <<comp-create-impl-non-opt,``Create
+implicit components from non-option arguments''>>) to create implicit
+components.
+
+An _implicit component_ is a component which is created and added to the
+conversion graph without an explicit instantiation through the
+opt:--component option. An implicit component is easier to create than
+an explicit component: this is why the `convert` command exists, as you
+can also create and run a conversion graph with the generic
+man:babeltrace2-run(1) command.
+
+For example, you can specify one or more CTF trace path as non-option
+arguments to pretty-print the merged events to the standard output:

 
 [role="term"]
 ----
 
 [role="term"]
 ----

-$ babeltrace2 /path/to/trace
+$ babeltrace2 /path/to/trace /path/to/other/trace

 ----
 
 This is the equivalent of creating and connecting together:
 
 ----
 
 This is the equivalent of creating and connecting together:
 

-* A compcls:src.ctf.fs component with its manparam:source.ctf.fs:path
-  initialization parameter set to `/path/to/trace`.
+* One compcls:source.ctf.fs components with its
+  manparam:source.ctf.fs:inputs initialization parameter set to
+  `/path/to/trace`.
+
+* One compcls:source.ctf.fs components with its
+  manparam:source.ctf.fs:inputs initialization parameter set to
+  `/path/to/other/trace`.

 
 * A compcls:filter.utils.muxer component.
 
 
 * A compcls:filter.utils.muxer component.
 


@@ -117,33 +138,44 @@ This is the equivalent of creating and connecting together:
 This creates the following conversion graph:
 
 ----
 This creates the following conversion graph:
 
 ----

-+------------+    +--------------------+    +------------------+
-| src.ctf.fs |    | filter.utils.muxer |    | sink.text.pretty |
-|  [ctf-fs]  |    |       [muxer]      |    |     [pretty]     |
-|            |    |                    |    |                  |
-|    stream0 @--->@                out @--->@ in               |
-|    stream1 @--->@                    |    +------------------+
-|    stream2 @--->@                    |
-|    stream3 @--->@                    |
-+------------+    +--------------------+
++------------+    +-----------------+    +------------------+
+| src.ctf.fs |    | flt.utils.muxer |    | sink.text.pretty |
+|  [ctf-fs]  |    |     [muxer]     |    |     [pretty]     |
+|            |    |                 |    |                  |
+|    stream0 @--->@ in0         out @--->@ in               |
+|    stream1 @--->@ in1             |    +------------------+
+|    stream2 @--->@ in2             |
+|    stream3 @--->@ in3             |
++------------+    |                 |
+                  |                 |
++------------+    |                 |
+| src.ctf.fs |    |                 |
+| [ctf-fs-2] |    |                 |
+|            |    |                 |
+|    stream0 @--->@ in4             |
+|    stream1 @--->@ in5             |
++------------+    @ in6             |
+                  +-----------------+

 ----
 
 ----
 

-It is equivalent to the following command:
+It is equivalent to the following man:babeltrace2-run(1) command line:

 
 [role="term"]
 ----
 $ babeltrace2 run --component=ctf-fs:src.ctf.fs \
 
 [role="term"]
 ----
 $ babeltrace2 run --component=ctf-fs:src.ctf.fs \

-                 --params=path=/path/to/trace \
-                 --component=pretty:sink.text.pretty \
-                 --component=muxer:filter.utils.muxer \
-                 --connect=ctf-fs:muxer --connect=muxer:pretty
+                  --params='inputs=["/path/to/trace"] \
+                  --component=ctf-fs-2:src.ctf.fs \
+                  --params='inputs=["/path/to/other/trace"] \
+                  --component=muxer:filter.utils.muxer \
+                  --component=pretty:sink.text.pretty \
+                  --connect=ctf*:muxer --connect=muxer:pretty

 ----
 
 You can use the opt:--run-args option to make the `convert` command
 ----
 
 You can use the opt:--run-args option to make the `convert` command

-print its equivalent man:babeltrace2-run(1) arguments instead of
-creating and running the conversion graph. The printed arguments are
-escaped for shells, which means you can use them as is on the command
-line and possibly add more options to the `run` command:
+print its equivalent `run` command arguments instead of creating and
+running the conversion graph. The printed arguments are escaped for
+shells, which means you can use them as is on the command line and
+possibly add more options to the `run` command:

 
 [role="term"]
 ----
 
 [role="term"]
 ----


@@ -156,17 +188,16 @@ character instead of a space. This is useful if the resulting arguments
 are not the direct input of a shell, for example if passed to
 `xargs -0`.
 
 are not the direct input of a shell, for example if passed to
 `xargs -0`.
 

-See <<examples,EXAMPLES>> for usage examples.
+See <<examples,``EXAMPLES''>> for usage examples.

 
 
 [[comp-create-expl]]
 
 
 [[comp-create-expl]]

-Create explicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Create explicit components
+

 To explicitly create a component, use the opt:--component option. This
 option specifies:
 
 To explicitly 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.
+* **Optional**: The name of the component.

 
 * The type of the component class to instantiate: source, filter, or
   sink.
 
 * The type of the component class to instantiate: source, filter, or
   sink.


@@ -182,95 +213,101 @@ multiple times as different component instances.
 
 Immediately following a opt:--component option on the command line, the
 created component is known as the _current component_ (until the next
 
 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).
+opt:--component option or non-option argument).

 
 

-The following, optional command-line options apply to the current
-component:
+The following command-line options apply to the current component:

 
 

-opt:--name='NAME'::
-    Set the name of the current component to 'NAME'.
+opt:--log-level='LVL'::
+    Set the log level of the current component to 'LVL'.

 
 opt:--params='PARAMS'::
     Add 'PARAMS' to the initialization parameters of the current
 
 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 <<params-fmt,Parameters format>> for the format of 'PARAMS'.
-
-opt:--path='PATH'::
-    Set the nlparam:path initialization parameter of the current
-    component to 'PATH' (replace the parameter if it exists).
+    component.

 +
 +

-You can use this option instead of manually specifying `path="PATH"` in
-a opt:--params option to use your shell's tilde expansion (`~`). Tilde
-expansion requires the tilde to be the first character of the argument,
-which is not possible with `path="PATH"`.
+If 'PARAMS' contains a key which exists in the current component's
+initialization parameters, replace the parameter.

 
 

-opt:--url='URL'::
-    Set the nlparam:url initialization parameter of the current
-    component to 'URL' (replace the parameter if it exists).
+See <<examples,``EXAMPLES''>> for usage examples.

 
 

-See <<examples,EXAMPLES>> for usage examples.

 
 

+[[comp-create-impl-non-opt]]
+=== Create implicit components from non-option arguments

 
 

-[[comp-create-impl]]
-Create implicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-An _implicit component_ is a component which is created and added to the
-conversion graph without an explicit instantiation through the
-opt:--component option. An implicit component is easier to create than
-an explicit component: this is why the `convert` command exists, as you
-can also create and run a conversion graph with the generic
-man:babeltrace2-run(1) command.
+When you specify a non-option argument to the `convert` command, it
+tries to find one or more components which can handle this argument.

 
 

-There are many ways to create implicit components with the `convert`
-command:
+For example, with this command line:

 
 

-* To create one or more implicit compcls:src.ctf.fs components (CTF
-  trace read from the file system), use one or more positional arguments
-  to specify the paths to the CTF traces to read, and do :not: specify
-  the opt:--input-format=`lttng-live` option.
-+
-Example:
-+

 [role="term"]
 ----
 [role="term"]
 ----

-$ babeltrace2 /path/to/trace /path/to/other/trace
+$ babeltrace2 /path/to/trace

 ----
 ----

+
+If `/path/to/trace` is a CTF trace directory, then the `convert` command
+creates a compcls:source.ctf.fs component to handle this specific trace.
+
+This automatic source component discovery mechanism is possible thanks
+to component classes which support the `babeltrace.support-info` query
+object (see man:babeltrace2-query-babeltrace.support-info(7)).
+
+The non-option argument can be a directory. If no component can handle
+that specific directory, then the `convert` command traverses that
+directory and recursively tries to find compatible components for each
+file and subdirectory. This means that a single non-option argument can
+lead to the creation of many implicit components.
+
+The following command-line options apply to :all: the implicit
+components created from the last non-option argument:
+
+opt:--log-level='LVL'::
+    Set the log level of those implicit components to 'LVL'.
+
+opt:--params='PARAMS'::
+    Add 'PARAMS' to the initialization parameters of those implicit
+    components.

 +
 +

-The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_
-the implicit compcls:src.ctf.fs components. For example:
-+
+For a given implicit component, if 'PARAMS' contains a key which exists
+in this component's initialization parameters, replace the parameter.
+
+Note that it's also possible for two non-option arguments to cause the
+creation of a single implicit component. For example, if you specify:
+

 [role="term"]
 ----
 [role="term"]
 ----

-$ babeltrace2 --clock-offset=3 trace1 trace2
+$ babeltrace2 /path/to/chunk1 /path/to/chunk2

 ----
 ----

-+
-With the command line above, two implicit compcls:src.ctf.fs components
-have their manparam:source.ctf.fs:clock-class-offset-s initialization
-parameter set to `3`, but they have different
-manparam:source.ctf.fs:path parameters (`trace1` and `trace2`).
-+
-You cannot create implicit compcls:src.ctf.fs components and an implicit
-compcls:src.ctf.lttng-live component.

 
 

-* To create an implicit compcls:src.ctf.lttng-live component
-  (http://lttng.org/docs/#doc-lttng-live[LTTng live] input), specify the
-  opt:--input-format=`lttng-live` option and the LTTng relay daemon's
-  URL with the positional argument.
-+
-Example:
-+
+where `/path/to/chunk1` and `/path/to/chunk2` are paths to chunks of the
+same logical CTF trace, then the `convert` command creates a single
+compcls:source.ctf.fs component which receives both paths at
+initialization time. When this happens, any opt:--log-level or
+opt:--params option that you specify to one of them applies to the
+single implicit component. For example:
+

 [role="term"]
 ----
 [role="term"]
 ----

-$ babeltrace2 --input-format=lttng-live \
-             net://localhost/host/abeille/my-session
+$ babeltrace2 /path/to/chunk1 --params=clock-class-offset-s=450 \
+              /path/to/chunk2 --params=clock-class-offset-ns=98 \
+              --log-level=INFO

 ----
 ----

-+
-You cannot create an implicit compcls:src.ctf.lttng-live component and
-implicit compcls:src.ctf.fs components.

 
 

-* To create an implicit compcls:filter.utils.trimmer component (trace
+Here, the single implicit component gets both `clock-class-offset-s` and
+`clock-class-offset-ns` initialization parameters, as well as the INFO
+log level.
+
+For backward compatibility with the man:babeltrace(1) program, the
+`convert` command ignores any non-option argument which does not cause
+the creation of any component. In that case, it emits a warning log
+statement and continues.
+
+
+[[comp-create-impl-opt]]
+=== Create implicit components from options
+
+There are many ways to create implicit components from options with the
+`convert` command:
+
+* To create an implicit compcls:filter.utils.trimmer component (stream

   trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
   option.
 +
   trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
   option.
 +


@@ -300,13 +337,13 @@ Examples:
 +
 [role="term"]
 ----
 +
 [role="term"]
 ----

-$ babeltrace2 --debug-info /path/to/trace
+$ babeltrace2 /path/to/trace --debug-info

 ----
 +
 [role="term"]
 ----
 $ babeltrace2 /path/to/trace \
 ----
 +
 [role="term"]
 ----
 $ babeltrace2 /path/to/trace \

-             --debug-info-target-prefix=/tmp/tgt-root
+              --debug-info-target-prefix=/tmp/tgt-root

 ----
 +
 [role="term"]
 ----
 +
 [role="term"]


@@ -315,24 +352,23 @@ $ babeltrace2 /path/to/trace --debug-info-full-path
 ----
 
 * To create an implicit compcls:sink.text.pretty component
 ----
 
 * To create an implicit compcls:sink.text.pretty component

-  (pretty-printing text output to the console or to a file), do any of:
+  (pretty-printing text output to the standard output or to a file),
+  specify no other sink components, explicit or implicit.

 +
 +

---
-* Specify no other sink components, <<comp-create-expl,explicit>> or
-  implicit. The compcls:sink.text.pretty implicit component is the
-  _default_ implicit sink component. If any other explicit or implicit
-  component exists, the default compcls:sink.text.pretty sink component
-  is not automatically created.
-
-* Specify any of the opt:--clock-cycles, opt:--clock-date,
-  opt:--clock-gmt, opt:--clock-seconds, opt:--color, opt:--fields,
-  opt:--names, or opt:--no-delta options. You can also specify the
-  opt:--output option without using the opt:--output-format=`ctf` option
-  (in which case opt:--output applies to the implicit
-  compcls:sink.ctf.fs component).
-
-* Specify the opt:--output-format=`text` option.
---
+The implicit compcls:sink.text.pretty component exists by default. If
+any other explicit or implicit sink component exists, the `convert`
+command does not automatically create the implicit
+compcls:sink.text.pretty component.
++
+The opt:--clock-cycles, opt:--clock-date, opt:--clock-gmt,
+opt:--clock-seconds, opt:--color, opt:--fields, opt:--names, and
+opt:--no-delta options all apply to the implicit
+compcls:sink.text.pretty component.
++
+The opt:--output option without opt:--output-format=`ctf` makes the
+implicit compcls:sink.text.pretty component write its content to a file,
+except the warnings for backward compatibility with the
+man:babeltrace(1) program.

 +
 Examples:
 +
 +
 Examples:
 +


@@ -348,17 +384,11 @@ $ babeltrace2 /path/to/trace --no-delta
 +
 [role="term"]
 ----
 +
 [role="term"]
 ----

-$ babeltrace2 /path/to/trace --output-format=text
-----
-+
-[role="term"]
-----

 $ babeltrace2 /path/to/trace --output=/tmp/pretty-out
 ----
 
 $ babeltrace2 /path/to/trace --output=/tmp/pretty-out
 ----
 

-* To create an implicit compcls:sink.utils.dummy component (dummy
-  output), specify the opt:--output-format=`dummy` option. This option
-  disables the default implicit compcls:sink.text.pretty component.
+* To create an implicit compcls:sink.utils.dummy component (no output),
+  specify the opt:--output-format=`dummy` option.

 +
 Example:
 +
 +
 Example:
 +


@@ -369,26 +399,24 @@ $ babeltrace2 /path/to/trace --output-format=dummy
 
 * To create an implicit compcls:sink.ctf.fs component (CTF traces
   written to the file system), specify the opt:--output-format=`ctf`
 
 * To create an implicit compcls:sink.ctf.fs component (CTF traces
   written to the file system), specify the opt:--output-format=`ctf`

-  option. This option disables the default implicit
-  compcls:sink.text.pretty component. Use the opt:--output option to
-  specify the output directory.
+  and the opt:--output='DIR' (base output directory) options.

 +
 Example:
 +
 [role="term"]
 ----
 $ babeltrace2 /path/to/input/trace --output-format=ctf \
 +
 Example:
 +
 [role="term"]
 ----
 $ babeltrace2 /path/to/input/trace --output-format=ctf \

-             --output=my-traces
+              --output=my-traces

 ----
 
 ----
 

-You can combine multiple methods to create implicit components. For
-example, you can trim an LTTng (CTF) trace, add debugging information to
-it, and write it as another CTF trace:
+You can combine multiple methods to create multiple implicit components.
+For example, you can trim an LTTng (CTF) trace, add debugging
+information to it, and write it as another CTF trace:

 
 [role="term"]
 ----
 $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \
 
 [role="term"]
 ----
 $ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \

-             --debug-info --output-format=ctf --output=out-dir
+              --debug-info --output-format=ctf --output=out-dir

 ----
 
 The equivalent man:babeltrace2-run(1) command of this `convert` command
 ----
 
 The equivalent man:babeltrace2-run(1) command of this `convert` command


@@ -396,76 +424,44 @@ is:
 
 [role="term"]
 ----
 
 [role="term"]
 ----

-$ babeltrace2 run --component=src-ctf-fs:src.ctf.fs \
-                 --params=path=/path/to/input/trace \
-                 --component=sink-ctf-fs:sink.ctf.fs \
-                 --params=path=out-dir \
-                 --component=muxer:flt.utils.muxer \
-                 --component=trimmer:flt.utils.trimmer \
-                 '--params=begin="22:14:38"' \
-                 '--params=end="22:15:07"' \
-                 --component=dbginfo:flt.lttng-utils.debug-info \
-                 --connect=src-ctf-fs:muxer --connect=muxer:trimmer \
-                 --connect=trimmer:dbg-info \
-                 --connect=dbginfo:sink-ctf-fs
+$ babeltrace2 run --component=auto-disc-source-ctf-fs:source.ctf.fs \
+                  --params='inputs=["/path/to/input/trace"]' \
+                  --component=sink-ctf-fs:sink.ctf.fs \
+                  --params='path="out-dir"' \
+                  --component=muxer:filter.utils.muxer \
+                  --component=trimmer:filter.utils.trimmer \
+                  --params='begin="22:14:38"' \
+                  --params='end="22:15:07"' \
+                  --component=debug-info:filter.lttng-utils.debug-info \
+                  --connect=auto-disc-source-ctf-fs:muxer \
+                  --connect=muxer:trimmer \
+                  --connect=trimmer:debug-info \
+                  --connect=debug-info:sink-ctf-fs

 ----
 
 ----
 

-See <<examples,EXAMPLES>> for more examples.
-
-
-include::common-cmd-params-format.txt[]
-
+The order of the implicit component options documented in this
+subsection is not significant.

 
 

-[[time-fmt]]
-Time option format
-~~~~~~~~~~~~~~~~~~
-The format of the arguments of the opt:--begin and opt:--end options
-is:
-
-[verse]
-$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
-
-'YYYY'::
-    4-digit year.
-
-'MM'::
-    2-digit month (January is `01`).
-
-'DD'::
-    2-digit day.
-
-'hh'::
-    2-digit hour (24-hour format).
+See <<examples,``EXAMPLES''>> for more examples.

 
 

-'mm'::
-    2-digit minute.

 
 

-'ss'::
-    2-digit second.
+== OPTIONS

 
 

-'nnnnnnnnn'::
-    9-digit nanosecond.
-
-
-include::common-cmd-plugin-path.txt[]
-
-
-OPTIONS
--------

 include::common-gen-options.txt[]
 
 
 include::common-gen-options.txt[]
 
 

-Explicit component creation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See <<comp-create-expl,Create explicit components>> to learn how to
-use the following options.
+=== Explicit component creation

 
 

-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.
+See <<comp-create-expl,``Create explicit components''>> to learn how to
+use the following option.
+
+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' (if specified) 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:
+The available values for 'COMP-CLS-TYPE' are:

 +
 --
 `source`::
 +
 --
 `source`::


@@ -480,111 +476,137 @@ The available values for 'TYPE' are:
     Sink component class.
 --
 
     Sink component class.
 --
 

-opt:--name='NAME'::
-    Set the name of the current component to 'NAME'. The names of all
-    the explicitly created components in the conversion graph must be
-    unique.

 
 

-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 <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+=== Common component creation
+
+See <<comp-create-expl,``Create explicit components''>> and
+<<comp-create-impl-non-opt,``Create implicit components from non-option
+arguments''>> to learn how to use the following options.

 
 

-opt:-P 'PATH', opt:--path='PATH'::
-    Set the nlparam:path initialization parameter of the current
-    component to 'PATH' (replace the parameter if it exists).
+The following options apply to either the current explicit component
+(last opt:--component option) or to :all: the implicit components
+created from the last non-option argument.
+
+opt:-l 'LVL'::
+opt:--log-level='LVL'::
+    Set the log level of the current component(s) to 'LVL'.
++
+The available values for 'LVL' are:
++
+--
+include::common-log-levels.txt[]
+--
+
+opt:-p 'PARAMS'::
+opt:--params='PARAMS'::
+    Add 'PARAMS' to the initialization parameters of the current
+    component(s).
++
+If 'PARAMS' contains a key which exists in the initialization parameters
+of the current component(s), replace the parameter.
++
+--
+include::common-cmd-params-format.txt[]
+--

 
 

-opt:-u 'URL', opt:--url='URL'::
-    Set the nlparam:url initialization parameter of the current
-    component to 'URL' (replace the parameter if it exists).

 
 

+=== Legacy options to create implicit components

 
 

-Legacy options to create implicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-opt:-i 'FORMAT', opt:--input-format='FORMAT'::
-    Create one or more implicit source components. The available values
-    for 'FORMAT' are:
+opt:-i 'FORMAT'::
+opt:--input-format='FORMAT'::
+    Force the `convert` command to create components from a specific
+    component class for non-option arguments (see
+    <<comp-create-impl-non-opt,``Create implicit components from
+    non-option arguments''>>), or list available remote LTTng tracing
+    sessions.
++
+The available values for 'FORMAT' are:

 +
 --
 `ctf`::
 +
 --
 `ctf`::

-    Create an implicit compcls:src.ctf.fs component for each positional
-    argument. Each positional argument sets the
-    manparam:source.ctf.fs:path initialization parameter of an
-    individual component. See <<impl-opts-ctf,Implicit
-    compcls:src.ctf.fs component>>.
+    Use the compcls:source.ctf.fs component class.
++
+Each non-option argument of the command line is a CTF trace or CTF
+trace chunk.

 +
 See man:babeltrace2-source.ctf.fs(7) to learn more about this
 component class.
 
 `lttng-live`::
 +
 See man:babeltrace2-source.ctf.fs(7) to learn more about this
 component class.
 
 `lttng-live`::

-    Depending on the format of the positional argument:
+    Depending on the format of the first non-option argument:

 +
 --
 +
 --

-`net[4]://RDHOST[:RDPORT]/host/TGTHOST`::
-    Print the available LTTng live sessions of the LTTng relay daemon at
-    the address `RDHOST` and port `RDPORT`, and then exit.
+`net[4]://RDHOST[:RDPORT]`::
+    List the available remote LTTng tracing sessions for the LTTng relay
+    daemon at the address `RDHOST` and port `RDPORT` ({defrdport} if not
+    specified), and then exit.

 
 `net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`::
 
 `net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`::

-    Create an implicit compcls:src.ctf.lttng-live component. The
-    position argument sets the manparam:source.ctf.lttng-live:url
-    parameter of the component.
-+
-Any other format for the positional argument is invalid.
+    Use the compcls:source.ctf.lttng-live component class.

 +
 +

-See man:babeltrace2-source.ctf.lttng-live(7) to learn more about
-this component class.
+See man:babeltrace2-source.ctf.lttng-live(7) to learn more about this
+component class and the URL format.

 --
 --
 +
 You can specify at most one opt:--input-format option.
 
 opt:-o 'FORMAT', opt:--output-format='FORMAT'::
 --
 --
 +
 You can specify at most one opt:--input-format option.
 
 opt:-o 'FORMAT', opt:--output-format='FORMAT'::

-    Create an implicit sink component. The available values for 'FORMAT'
-    are:
+    Create an implicit sink component with format 'FORMAT' or print
+    the metadata text of a CTF trace.
++
+The available values for 'FORMAT' are:

 +
 --
 `text`::
     Create an implicit compcls:sink.text.pretty component.
 +
 --
 `text`::
     Create an implicit compcls:sink.text.pretty component.

-    See <<impl-opts-text,Implicit compcls:sink.text.pretty component>>.

 +
 +

-See man:babeltrace2-sink.text.pretty(7) to learn more about
-this component class.
+See <<impl-opts-text,``Implicit compcls:sink.text.pretty component''>>.
++
+See man:babeltrace2-sink.text.pretty(7) to learn more about this
+component class.

 
 `ctf`::
 
 `ctf`::

-    Create an implicit compcls:sink.ctf.fs component. Specify the output
-    path with the opt:--output option.
+    Create an implicit compcls:sink.ctf.fs component. Specify the base
+    output path with the opt:--output option.

 +
 +

-See man:babeltrace2-sink.ctf.fs(7) to learn more about
-this component class.
+See man:babeltrace2-sink.ctf.fs(7) to learn more about this component
+class.

 
 `dummy`::
     Create an implicit compcls:sink.utils.dummy component.
 +
 
 `dummy`::
     Create an implicit compcls:sink.utils.dummy component.
 +

-See man:babeltrace2-sink.utils.dummy(7) to learn more about
-this component class.
+See man:babeltrace2-sink.utils.dummy(7) to learn more about this
+component class.

 
 `ctf-metadata`::
 
 `ctf-metadata`::

-    Print the metadata text of a CTF trace and exit. The first
-    positional argument specifies the path to the CTF trace.
+    Print the metadata text of a CTF trace and exit.
++
+The first non-option argument specifies the path to the CTF trace.

 --
 +
 You can specify at most one opt:--output-format option.
 
 
 [[impl-opts-ctf]]
 --
 +
 You can specify at most one opt:--output-format option.
 
 
 [[impl-opts-ctf]]

-Implicit compcls:src.ctf.fs component(s)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is one implicit compcls:src.ctf.fs component per positional
-argument (which are trace paths), unless you specify
-opt:--input-format=`lttng-live`.
+=== Implicit compcls:source.ctf.fs component(s)

 
 

-See man:babeltrace2-source.ctf.fs(7) to learn more about this
-component class.
+See man:babeltrace2-source.ctf.fs(7) to learn more about this component
+class.
+
+opt:--clock-force-correlate::
+    Set the manparam:source.ctf.fs:force-clock-class-origin-unix-epoch
+    initialization parameter of all the implicit compcls:source.ctf.fs
+    components to true.
++
+The manparam:source.ctf.fs:force-clock-class-origin-unix-epoch
+initialization parameter makes all the created clock classes have a Unix
+epoch origin. This is useful to force the clock classes of multiple
+traces to be compatible even if they are not inherently.

 
 opt:--clock-offset='SEC'::
     Set the manparam:source.ctf.fs:clock-class-offset-s initialization
 
 opt:--clock-offset='SEC'::
     Set the manparam:source.ctf.fs:clock-class-offset-s initialization

-    parameter of all the implicit compcls:src.ctf.fs components to
+    parameter of all the implicit compcls:source.ctf.fs components to

     'SEC'.
 +
 The manparam:source.ctf.fs:clock-class-offset-s initialization parameter
     'SEC'.
 +
 The manparam:source.ctf.fs:clock-class-offset-s initialization parameter


@@ -595,7 +617,7 @@ You can combine this option with opt:--clock-offset-ns.
 
 opt:--clock-offset-ns='NS'::
     Set the manparam:source.ctf.fs:clock-class-offset-ns initialization
 
 opt:--clock-offset-ns='NS'::
     Set the manparam:source.ctf.fs:clock-class-offset-ns initialization

-    parameter of all the implicit compcls:src.ctf.fs components to
+    parameter of all the implicit compcls:source.ctf.fs components to

     'NS'.
 +
 The manparam:source.ctf.fs:clock-class-offset-ns initialization
     'NS'.
 +
 The manparam:source.ctf.fs:clock-class-offset-ns initialization


@@ -605,44 +627,53 @@ that the component creates.
 You can combine this option with opt:--clock-offset-s.
 
 
 You can combine this option with opt:--clock-offset-s.
 
 

-Implicit compcls:filter.utils.trimmer component
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Implicit compcls:filter.utils.trimmer component
+

 If you specify at least one of the following options, you create an
 implicit compcls:filter.utils.trimmer component.
 
 See man:babeltrace2-filter.utils.trimmer(7) to learn more about
 this component class.
 
 If you specify at least one of the following options, you create an
 implicit compcls:filter.utils.trimmer component.
 
 See man:babeltrace2-filter.utils.trimmer(7) to learn more about
 this component class.
 

-See <<time-fmt,Time option format>> for the format of 'BEGIN' and 'END'.
-
-opt:--begin='BEGIN'::
+opt:--begin='TIME'::

     Set the manparam:filter.utils.trimmer:begin initialization parameter
     Set the manparam:filter.utils.trimmer:begin initialization parameter

-    of the component to 'BEGIN'. You cannot use this option with the
-    opt:--timerange option.
+    of the component to 'TIME'.
++
+You cannot use this option with the opt:--timerange option.
++
+The format of 'TIME' is one of:
++
+--
+include::common-trimmer-time-format.txt[]
+--

 
 

-opt:--end='END'::
+opt:--end='TIME'::

     Set the manparam:filter.utils.trimmer:end initialization parameter
     Set the manparam:filter.utils.trimmer:end initialization parameter

-    of the component to 'END'. You cannot use this option with the
-    opt:--timerange option.
+    of the component to 'TIME'.
++
+You cannot use this option with the opt:--timerange option.
++
+See the opt:--begin option for the format of 'TIME'.

 
 opt:--timerange='BEGIN','END'::
 
 opt:--timerange='BEGIN','END'::

-    Equivalent to opt:--begin='BEGIN' opt:--end='END'.
+    Equivalent to opt:--begin='BEGIN' and opt:--end='END'.

 +
 You can also surround the whole argument with `[` and `]`.
 
 
 +
 You can also surround the whole argument with `[` and `]`.
 
 

-Implicit compcls:filter.lttng-utils.debug-info component
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== Implicit compcls:filter.lttng-utils.debug-info component
+

 If you specify at least one of the following options, you create an
 implicit compcls:filter.lttng-utils.debug-info component. This component
 only alters compatible LTTng events.
 
 If you specify at least one of the following options, you create an
 implicit compcls:filter.lttng-utils.debug-info component. This component
 only alters compatible LTTng events.
 

-See man:babeltrace2-filter.lttng-utils.debug-info(7) to learn more
-about this component class.
+See man:babeltrace2-filter.lttng-utils.debug-info(7) to learn more about
+this component class.

 
 opt:--debug-info::
     Create an implicit compcls:filter.lttng-utils.debug-info component.
 
 opt:--debug-info::
     Create an implicit compcls:filter.lttng-utils.debug-info component.

-    This option is useless if you specify any of the options below.
++
+This option is useless if you specify any of the options below.

 
 opt:--debug-info-dir='DIR'::
     Set the manparam:filter.lttng-utils.debug-info:debug-info-dir
 
 opt:--debug-info-dir='DIR'::
     Set the manparam:filter.lttng-utils.debug-info:debug-info-dir


@@ -676,10 +707,9 @@ debugging information.
 [[impl-opts-text]]
 === Implicit compcls:sink.text.pretty component
 
 [[impl-opts-text]]
 === Implicit compcls:sink.text.pretty component
 

-If you specify at least one of the following options, you create an
-implicit compcls:sink.text.pretty component. The `convert` command also
-creates a default implicit compcls:sink.text.pretty component if no
-other sink component exists.
+If you specify at least one of the following options, you force the
+`convert` command's sink component to be an implicit
+compcls:sink.text.pretty component.

 
 See man:babeltrace2-sink.text.pretty(7) to learn more about this
 component class.
 
 See man:babeltrace2-sink.text.pretty(7) to learn more about this
 component class.


@@ -710,7 +740,7 @@ opt:--clock-seconds::
     parameter of the component to true.
 +
 The manparam:sink.text.pretty:clock-seconds parameter makes the
     parameter of the component to true.
 +
 The manparam:sink.text.pretty:clock-seconds parameter makes the

-component print the event times in seconds since Epoch.
+component print the event times in seconds since the Unix epoch.

 
 opt:--color='WHEN'::
     Set the manparam:sink.text.pretty:color initialization parameter of
 
 opt:--color='WHEN'::
     Set the manparam:sink.text.pretty:color initialization parameter of


@@ -720,9 +750,8 @@ The available values for 'WHEN' are:
 +
 --
 `auto`::
 +
 --
 `auto`::

-    Automatic color support depending on the capabilities of the
-    terminal(s) to which the standard output and error streams are
-    connected.
+    Only emit terminal color codes when the standard output and error
+    streams are connected to a color-capable terminal.

 
 `never`::
     Never emit terminal color codes.
 
 `never`::
     Never emit terminal color codes.


@@ -777,229 +806,118 @@ When the manparam:sink.text.pretty:no-delta parameter is true, the
 component does not print the duration since the last event on the line.
 
 
 component does not print the duration since the last event on the line.
 
 

-Shared options
-~~~~~~~~~~~~~~
-opt:-w 'PATH', opt:--output='PATH'::
+=== Shared options
+
+opt:-w 'PATH'::
+opt:--output='PATH'::

     With opt:--output-format=`ctf-metadata` or
     With opt:--output-format=`ctf-metadata` or

-    opt:--input-format=`lttng-live` (when printing the available LTTng
-    live sessions), write the text to the file 'PATH' instead of the
-    standard output.
+    opt:--input-format=`lttng-live` (when printing the available remote
+    LTTng tracing sessions), write the text to the file 'PATH' instead
+    of the standard output.

 +
 When you specify opt:--output-format=`ctf`, set the
 manparam:sink.ctf.fs:path initialization parameter of the implicit
 +
 When you specify opt:--output-format=`ctf`, set the
 manparam:sink.ctf.fs:path initialization parameter of the implicit

-compcls:sink.ctf.fs component to 'PATH'. Otherwise, create an implicit
+compcls:sink.ctf.fs component to 'PATH'.
++
+Without any specified sink component, explicit or implicit, force the
+`convert` command's sink component to be an implicit

 compcls:sink.text.pretty component and set its
 manparam:sink.text.pretty:path initialization parameter to 'PATH'.
 +
 See man:babeltrace2-sink.ctf.fs(7) and
 compcls:sink.text.pretty component and set its
 manparam:sink.text.pretty:path initialization parameter to 'PATH'.
 +
 See man:babeltrace2-sink.ctf.fs(7) and

-man:babeltrace2-sink.text.pretty(7) to learn more about those
-component classes.
+man:babeltrace2-sink.text.pretty(7) to learn more about those component
+classes.
+

 
 

+=== Equivalent `babeltrace2 run` arguments

 
 

-Equivalent `babeltrace2 run` arguments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 opt:--run-args::
     Print the equivalent man:babeltrace2-run(1) arguments instead of
 opt:--run-args::
     Print the equivalent man:babeltrace2-run(1) arguments instead of

-    creating and running the conversion graph. The printed arguments are
-    space-separated and individually escaped for safe shell input.
+    creating and running the conversion graph.
++
+The printed arguments are space-separated and individually escaped for
+safe shell input.

 +
 You cannot use this option with the opt:--run-args-0 or
 opt:--stream-intersection option.
 
 opt:--run-args-0::
     Print the equivalent man:babeltrace2-run(1) arguments instead of
 +
 You cannot use this option with the opt:--run-args-0 or
 opt:--stream-intersection option.
 
 opt:--run-args-0::
     Print the equivalent man:babeltrace2-run(1) arguments instead of

-    creating and running the conversion graph. The printed arguments are
-    separated with a null character and :not: escaped for safe shell
-    input.
+    creating and running the conversion graph.
++
+The printed arguments are separated with a null character and :not:
+escaped for safe shell input.

 +
 You cannot use this option with the opt:--run-args or
 opt:--stream-intersection option.
 
 
 +
 You cannot use this option with the opt:--run-args or
 opt:--stream-intersection option.
 
 

-Conversion graph configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-opt:--retry-duration='DURUS'::
-    Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+=== Conversion graph configuration
+
+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).
 +
     component reports "try again later" (busy network or file system,
     for example).
 +

-Default: 100000 (100{nbsp}ms).
+Default: 100000 (100~ms).

 
 opt:--stream-intersection::
 
 opt:--stream-intersection::

-    Enable the stream intersection mode. In this mode, for each trace,
-    the `convert` command filters out the events and other notifications
-    which are not in the time range where _all_ the trace's streams are
-    active.
+    Enable the stream intersection mode.

 +
 +

-All the source components, <<comp-create-expl,explicit>> and
-<<comp-create-impl,implicit>>, must have classes which support the
-`trace-info` query object to use this option. The only Babeltrace
-project's component class which supports this query object is
-compcls:source.ctf.fs.
+In this mode, for each trace, the `convert` command filters out the
+events and other messages which are not in the time range where _all_
+the trace's streams are active.

 +
 +

-Because it is not possible to replicate with a single
-man:babeltrace2-run(1) command line what the `convert` method does with
-the opt:--stream-intersection option, you cannot use this option with
-the opt:--run-args or opt:--run-args-0 option.
-
+To use this option, all the source components, explicit and implicit,
+must have classes which support the `babeltrace.trace-infos` query
+object (see man:babeltrace2-query-babeltrace.trace-infos(7)). The only
+Babeltrace~2 project's component class which supports this query
+object is compcls:source.ctf.fs.
++
+You cannot use this option with the opt:--run-args or opt:--run-args-0
+option.

 
 

-Plugin path
-~~~~~~~~~~~
-opt:--omit-home-plugin-path::
-    Do not search for plugins in `$HOME/.local/lib/babeltrace2/plugins`.
+=== Other legacy options

 
 

-opt:--omit-system-plugin-path::
-    Do not search for plugins in +{system_plugin_path}+.
+The following options exist for backward compatibility with the
+man:babeltrace(1) program.

 
 

-opt:--plugin-path='PATH'[:__PATH__]...::
-    Add 'PATH' to the list of paths in which dynamic plugins can be
-    found.
+opt:-d::
+opt:--debug::
+    Legacy option: this is equivalent to nlopt:--log-level=`TRACE`,
+    where nlopt:--log-level is the general option (not this command's
+    opt:--log-level option).

 
 

+opt:-v::
+opt:--verbose::
+    Legacy option: this is equivalent to nlopt:--log-level=`INFO`, where
+    nlopt:--log-level is the general option (not this command's
+    opt:--log-level option).
++
+This option also sets the manparam:sink.text.pretty:verbose parameter of
+the implicit compcls:sink.text.pretty component (see
+man:babeltrace2-sink.text.pretty(7)) to true.

 
 

-Command information
-~~~~~~~~~~~~~~~~~~~
-opt:-h, opt:--help::
-    Show command help and quit.
+include::common-cmd-info-options.txt[]

 
 
 [[examples]]
 
 
 [[examples]]

-EXAMPLES
---------
-.Pretty-print the events of one or more CTF traces.
-====
-[role="term"]
-----
-$ babeltrace2 my-trace
-----
+== EXAMPLES

 
 

-[role="term"]
-----
-$ babeltrace2 my-traces
-----
-
-[role="term"]
-----
-$ babeltrace2 my-trace-1 my-trace-2 my-trace-3
-----
-====
-
-.Trim a CTF trace and pretty-print the events.
-====
-[role="term"]
-----
-$ babeltrace2 my-trace --begin=22:55:43.658582931 \
-             --end=22:55:46.967687564
-----
-
-[role="term"]
-----
-$ babeltrace2 my-trace --begin=22:55:43.658582931
-----
-
-[role="term"]
-----
-$ babeltrace2 my-trace --end=22:55:46.967687564
-----
-
-[role="term"]
-----
-$ babeltrace2 my-trace --timerange=22:55:43,22:55:46.967687564
-----
-====
-
-.Trim a CTF trace, enable the stream intersection mode, and generate a CTF trace.
-====
-[role="term"]
-----
-$ babeltrace2 my-trace --stream-intersection \
-             --timerange=22:55:43,22:55:46.967687564 \
-             --output-format=ctf --output=out-trace
-----
-====
-
-.Record LTTng live traces to the file system (as CTF traces).
-====
-[role="term"]
-----
-$ babeltrace2 --input-format=lttng-live \
-             net://localhost/host/myhostname/auto-20170411-134512 \
-             --output-format=ctf --output=/path/to/generated/traces
-----
-====
-
-.Read a CTF trace as fast as possible using a dummy output.
-====
-[role="term"]
-----
-$ babeltrace2 my-trace --output-format=dummy
-----
-====
-
-.Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file.
-====
-[role="term"]
-----
-$ babeltrace2 trace1 trace2 trace3 --stream-intersection \
-             --debug-info --output=pretty-out
-----
-====
-
-.Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since Epoch.
-====
-[role="term"]
-----
-$ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
-             --params=output-some-event-type=yes --clock-seconds
-----
-====
-
-.Send LTTng live events to an explicit sink component.
-====
-[role="term"]
-----
-$ babeltrace2 --input-format=lttng-live \
-             net://localhost/host/myhostname/mysession \
-             --component=sink.my-plugin.my-sink
-----
-====
-
-.Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace.
-====
-[role="term"]
-----
-$ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07 \
-             --debug-info --component=filter.my-plugin.my-filter \
-             --params=criteria=xyz,ignore-abc=yes \
-             --output-format=ctf --output=out-trace
-----
-====
-
-.Print the metadata text of a CTF trace.
-====
-[role="term"]
-----
-$ babeltrace2 /path/to/trace --output-format=ctf-metadata
-----
-====
-
-.Print the available LTTng live sessions of an LTTng relay daemon.
-====
-[role="term"]
-----
-$ babeltrace2 --input-format=lttng-live net://localhost
-----
-====
+include::common-convert-examples.txt[]

 
 
 include::common-cli-env.txt[]
 
 
 
 include::common-cli-env.txt[]
 

+

 include::common-cli-files.txt[]
 
 include::common-cli-files.txt[]
 

+

 include::common-cmd-footer.txt[]
 
 
 include::common-cmd-footer.txt[]
 
 

-SEE ALSO
---------
+== SEE ALSO
+
+man:babeltrace2-intro(7),

 man:babeltrace2(1),
 man:babeltrace2(1),

-man:babeltrace2-run(1),
-man:babeltrace2-intro(7)
+man:babeltrace2-run(1)