Add modern Babeltrace man pages

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

babeltrace-convert(1)
=====================
:manpagetype: command
:revdate: 5 October 2017


NAME
----
babeltrace-convert - Convert one or more traces


SYNOPSIS
--------
Convert one or more traces:

[verse]
*babeltrace 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'

Print the metadata text of a CTF trace:

[verse]
*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
                   [opt:--omit-system-plugin-path]
                   [opt:--plugin-path='PATH'[:__PATH__]...]
                   opt:--output-format=`ctf-metadata` 'TRACE-PATH'

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

[verse]
*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
                   [opt:--omit-system-plugin-path]
                   [opt:--plugin-path='PATH'[:__PATH__]...]
                   opt:--input-format=`lttng-live` 'URL'


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

See man:babeltrace-intro(7) to learn more about the Babeltrace
project and its core concepts.

[NOTE]
====
`convert` is the default man:babeltrace(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:babeltrace(1)
command's name, like `run` or `list-plugins`:

[role="term"]
----
$ babeltrace convert ...
$ babeltrace ...
----

If you need to make sure that you are executing the `convert` command,
use `babeltrace convert` explicitly.
====

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:

----
+----------+
| source 1 |-.
+----------+ |
             |  +-------+
+----------+ '->|       |    +---------+    +------------+
| source 2 |--->| muxer |--->| trimmer |--->| debug-info |-.
+----------+ .->|       |    +---------+    +------------+ |
             |  +-------+                                  |
+----------+ |    .----------------------------------------'
|   ...    |-'    |  +---------------+    +------+
+----------+      '->| other filters |--->| sink |
                     +---------------+    +------+
----

Note that the trimmer, debugging information, and other filters are
optional. See <<comp-create-impl,Create implicit components>> to learn
how to enable them.

If you need another processing graph layout, use the more flexible
man:babeltrace-run(1) command.

Like with the man:babeltrace-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:

[role="term"]
----
$ babeltrace /path/to/trace
----

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`.

* A compcls:filter.utils.muxer component.

* A compcls:sink.text.pretty component.

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 @--->@                    |
+------------+    +--------------------+
----

It is equivalent to the following command:

[role="term"]
----
$ babeltrace run --component=ctf-fs:src.ctf.fs \
                 --key=path --value=/path/to/trace \
                 --component=pretty:sink.text.pretty \
                 --component=muxer:filter.utils.muxer \
                 --connect=ctf-fs:muxer --connect=muxer:pretty
----

You can use the opt:--run-args option to make the `convert` command
print its equivalent man:babeltrace-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:

[role="term"]
----
$ babeltrace run $(babeltrace --run-args /path/to/trace) ...
----

The opt:--run-args-0 option is like the opt:--run-args option, but the
printed arguments are :not: escaped and they are separated by a null
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`.

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


[[comp-create-expl]]
Create explicit components
~~~~~~~~~~~~~~~~~~~~~~~~~~
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.

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

* The name of the plugin in which to find the component class to
  instantiate.

* 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.

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 <<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).
+
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"`.

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.


[[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:babeltrace-run(1) command.

There are many ways to create implicit components with the `convert`
command:

* 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"]
----
$ babeltrace /path/to/trace /path/to/other/trace
----
+
The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_
the implicit compcls:src.ctf.fs components. For example:
+
[role="term"]
----
$ babeltrace --clock-offset=3 trace1 trace2
----
+
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:
+
[role="term"]
----
$ babeltrace --input-format=lttng-live \
             net://localhost/host/abeille/my-session
----
+
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
  trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
  option.
+
Examples:
+
[role="term"]
----
$ babeltrace /path/to/trace --begin=22:14:38 --end=22:15:07
----
+
[role="term"]
----
$ babeltrace /path/to/trace --timerange=22:14:38,22:15:07
----
+
[role="term"]
----
$ babeltrace /path/to/trace --end=12:31:04.882928015
----

* To create an implicit compcls:filter.lttng-utils.debug-info (add
  debugging information to compatible LTTng events), specify any of the
  opt:--debug-info, opt:--debug-info-dir, opt:--debug-info-full-path, or
  opt:--debug-info-target-prefix options.
+
Examples:
+
[role="term"]
----
$ babeltrace --debug-info /path/to/trace
----
+
[role="term"]
----
$ babeltrace /path/to/trace \
             --debug-info-target-prefix=/tmp/tgt-root
----
+
[role="term"]
----
$ babeltrace /path/to/trace --debug-info-full-path
----

* To create an implicit compcls:sink.text.pretty component
  (pretty-printing text output to the console or to a file), do any of:
+
--
* 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.
--
+
Examples:
+
[role="term"]
----
$ babeltrace /path/to/trace
----
+
[role="term"]
----
$ babeltrace /path/to/trace --no-delta
----
+
[role="term"]
----
$ babeltrace /path/to/trace --output-format=text
----
+
[role="term"]
----
$ babeltrace /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.
+
Example:
+
[role="term"]
----
$ babeltrace /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`
  option. This option disables the default implicit
  compcls:sink.text.pretty component. Use the opt:--output option to
  specify the output directory.
+
Example:
+
[role="term"]
----
$ babeltrace /path/to/input/trace --output-format=ctf \
             --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:

[role="term"]
----
$ babeltrace /path/to/input/trace --timerange=22:14:38,22:15:07 \
             --debug-info --output-format=ctf --output=out-dir
----

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

[role="term"]
----
$ babeltrace run --component=src-ctf-fs:src.ctf.fs \
                 --key=path --value=/path/to/input/trace \
                 --component=sink-ctf-fs:sink.ctf.fs \
                 --key=path --value=out-dir \
                 --component=muxer:flt.utils.muxer \
                 --component=trimmer:flt.utils.trimmer \
                 --key=begin --value=22:14:38 \
                 --key=end --value=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
----

See <<examples,EXAMPLES>> for more examples.


include::common-cmd-params-format.txt[]


[[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).

'mm'::
    2-digit minute.

'ss'::
    2-digit second.

'nnnnnnnnn'::
    9-digit nanosecond.


include::common-cmd-plugin-path.txt[]


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


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

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.
+
The available values for 'TYPE' are:
+
--
`source`::
`src`::
    Source component class.

`filter`::
`flt`::
    Filter component class.

`sink`::
    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'.

opt:-P 'PATH', opt:--path='PATH'::
    Set the nlparam:path initialization parameter of the current
    component to 'PATH' (replace the parameter if it exists).

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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
opt:-i 'FORMAT', opt:--input-format='FORMAT'::
    Create one or more implicit source components. The available values
    for 'FORMAT' are:
+
--
`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>>.
+
See man:babeltrace-source.ctf.fs(7) to learn more about this
component class.

`lttng-live`::
    Depending on the format of the positional 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]/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.
+
See man:babeltrace-source.ctf.lttng-live(7) to learn more about
this component class.
--
--
+
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:
+
--
`text`::
    Create an implicit compcls:sink.text.pretty component.
    See <<impl-opts-text,Implicit compcls:sink.text.pretty component>>.
+
See man:babeltrace-sink.text.pretty(7) to learn more about
this component class.

`ctf`::
    Create an implicit compcls:sink.ctf.fs component. Specify the output
    path with the opt:--output option.
+
See man:babeltrace-sink.ctf.fs(7) to learn more about
this component class.

`dummy`::
    Create an implicit compcls:sink.utils.dummy component.
+
See man:babeltrace-sink.utils.dummy(7) to learn more about
this component class.

`ctf-metadata`::
    Print the metadata text of a CTF trace and exit. The first
    positional argument specifies the path to the CTF trace.
--
+
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`.

See man:babeltrace-source.ctf.fs(7) to learn more about this
component class.

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
    'SEC'.
+
The manparam:source.ctf.fs:clock-class-offset-s initialization parameter
adds 'SEC' seconds to the offsets of all the clock classes that the
component creates.
+
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
    parameter of all the implicit compcls:src.ctf.fs components to
    'NS'.
+
The manparam:source.ctf.fs:clock-class-offset-ns initialization
parameter adds 'NS' nanoseconds to the offsets of all the clock classes
that the component creates.
+
You can combine this option with opt:--clock-offset-s.


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:babeltrace-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'::
    Set the manparam:filter.utils.trimmer:begin initialization parameter
    of the component to 'BEGIN'. You cannot use this option with the
    opt:--timerange option.

opt:--end='END'::
    Set the manparam:filter.utils.trimmer:end initialization parameter
    of the component to 'END'. You cannot use this option with the
    opt:--timerange option.

opt:--timerange='BEGIN','END'::
    Equivalent to opt:--begin='BEGIN' opt:--end='END'.
+
You can also surround the whole argument with `[` and `]`.


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.

See man:babeltrace-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.
    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
    initialization parameter of the component to 'DIR'.
+
The manparam:filter.lttng-utils.debug-info:debug-info-dir parameter
indicates where the component should find the debugging information it
needs if it's not found in the actual executable files.

opt:--debug-info-full-path::
    Set the manparam:filter.lttng-utils.debug-info:full-path
    initialization parameter of the component to true.
+
When the manparam:filter.lttng-utils.debug-info:full-path parameter is
true, the component writes the full (absolute) paths to files in its
debugging information fields instead of just the short names.

opt:--debug-info-target-prefix='PREFIX'::
    Set the manparam:filter.lttng-utils.debug-info:target-prefix
    initialization parameter of the component to 'PREFIX'.
+
The manparam:filter.lttng-utils.debug-info:target-prefix parameter is a
path to prepend to the paths to executables recorded in the trace. For
example, if a trace contains the executable path `/usr/bin/ls` in its
state dump events, and you specify
opt:--debug-info-target-prefix=`/home/user/boards/xyz/root`, then the
component opens the `/home/user/boards/xyz/root/usr/bin/ls` file to find
debugging information.


[[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.

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

opt:--clock-cycles::
    Set the manparam:sink.text.pretty:clock-seconds initialization
    parameter of the component to true.
+
The manparam:sink.text.pretty:clock-cycles parameter makes the component
print the event time in clock cycles.

opt:--clock-date::
    Set the manparam:sink.text.pretty:clock-date initialization
    parameter of the component to true.
+
The manparam:sink.text.pretty:clock-date parameter makes the component
print the date and the time of events.

opt:--clock-gmt::
    Set the manparam:sink.text.pretty:clock-gmt initialization parameter
    of the component to true.
+
The manparam:sink.text.pretty:clock-gmt parameter makes the component
not apply the local timezone to the printed times.

opt:--clock-seconds::
    Set the manparam:sink.text.pretty:clock-seconds initialization
    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.

opt:--color='WHEN'::
    Set the manparam:sink.text.pretty:color initialization parameter of
    the component to 'WHEN'.
+
The available values for 'WHEN' are:
+
--
`auto`::
    Automatic color support depending on the capabilities of the
    terminal(s) to which the standard output and error streams are
    connected.

`never`::
    Never emit terminal color codes.

`always`::
    Always emit terminal color codes.
--
+
The `auto` and `always` values have no effect if the
`BABELTRACE_TERM_COLOR` environment variable is set to `NEVER`.

opt:--fields='FIELD'[,'FIELD']...::
    For each 'FIELD', set the nlparam:field-FIELD initialization
    parameter of the component to true.
+
For example, opt:--fields=`trace,loglevel,emf` sets the
manparam:sink.text.pretty:field-trace,
manparam:sink.text.pretty:field-loglevel, and
manparam:sink.text.pretty:field-emf initialization parameters to true.
+
The available value for 'FIELD' are:
+
* `trace`
* `trace:hostname`
* `trace:domain`
* `trace:procname`
* `trace:vpid`
* `loglevel`
* `emf`
* `callsite`

opt:--names='NAME'[,'NAME']...::
    For each 'NAME', set the nlparam:name-NAME initialization parameter
    of the component to true.
+
For example, opt:--names=`payload,scope` sets the
manparam:sink.text.pretty:name-payload and
manparam:sink.text.pretty:name-scope initialization parameters to true.
+
The available value for 'NAME' are:
+
* `payload`
* `context`
* `scope`
* `header`

opt:--no-delta::
    Set the manparam:sink.text.pretty:no-delta initialization parameter
    of the component to true.
+
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.


Shared options
~~~~~~~~~~~~~~
opt:-w 'PATH', opt:--output='PATH'::
    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.text.pretty component and set its
    manparam:sink.text.pretty:path initialization parameter to 'PATH'.
+
See man:babeltrace-sink.ctf.fs(7) and
man:babeltrace-sink.text.pretty(7) to learn more about those
component classes.


Equivalent `babeltrace run` arguments
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
opt:--run-args::
    Print the equivalent man:babeltrace-run(1) arguments instead of
    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:babeltrace-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.
+
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
    component reports "try again later" (busy network or file system,
    for example).
+
Default: 100000 (100{nbsp}ms).

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.
+
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.
+
Because it is not possible to replicate with a single
man:babeltrace-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.


Plugin path
~~~~~~~~~~~
opt:--omit-home-plugin-path::
    Do not search for plugins in `$HOME/.local/lib/babeltrace/plugins`.

opt:--omit-system-plugin-path::
    Do not search for plugins in +{system_plugin_path}+.

opt:--plugin-path='PATH'[:__PATH__]...::
    Add 'PATH' to the list of paths in which dynamic plugins can be
    found.


Command information
~~~~~~~~~~~~~~~~~~~
opt:-h, opt:--help::
    Show command help and quit.


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

[role="term"]
----
$ babeltrace my-traces
----

[role="term"]
----
$ babeltrace my-trace-1 my-trace-2 my-trace-3
----
====

.Trim a CTF trace and pretty-print the events.
====
[role="term"]
----
$ babeltrace my-trace --begin=22:55:43.658582931 \
             --end=22:55:46.967687564
----

[role="term"]
----
$ babeltrace my-trace --begin=22:55:43.658582931
----

[role="term"]
----
$ babeltrace my-trace --end=22:55:46.967687564
----

[role="term"]
----
$ babeltrace 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"]
----
$ babeltrace 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"]
----
$ babeltrace --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"]
----
$ babeltrace 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"]
----
$ babeltrace 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"]
----
$ babeltrace 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"]
----
$ babeltrace --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"]
----
$ babeltrace /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"]
----
$ babeltrace /path/to/trace --output-format=ctf-metadata
----
====

.Print the available LTTng live sessions of an LTTng relay daemon.
====
[role="term"]
----
$ babeltrace --input-format=lttng-live net://localhost
----
====


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

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

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


SEE ALSO
--------
man:babeltrace(1),
man:babeltrace-run(1),
man:babeltrace-intro(7)