-babeltrace2-convert(1)
-=====================
+= babeltrace2-convert(1)
: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]
-*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]
-*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]
-*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]
====
-`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"]
----
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
-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
-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
-<<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"]
----
-$ babeltrace2 /path/to/trace
+$ babeltrace2 /path/to/trace /path/to/other/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`.
+* 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.
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 \
- --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
-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"]
----
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]]
-Create explicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+=== 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.
+* **Optional**: The name of the component.
* The type of the component class to instantiate: source, filter, or
sink.
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
- component. If 'PARAMS' contains a key which exists in the current
- component's initialization parameters, this parameter is replaced.
+ component.
+
-See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+If 'PARAMS' contains a key which exists in the current component's
+initialization parameters, replace the parameter.
-See <<examples,EXAMPLES>> for usage examples.
+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:babeltrace2-run(1) command.
+[[comp-create-impl-non-opt]]
+=== Create implicit components from non-option arguments
-There are many ways to create implicit components with the `convert`
-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.
+
+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"]
----
-$ 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"]
----
-$ 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"]
----
-$ 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.
+
+
[role="term"]
----
-$ babeltrace2 --debug-info /path/to/trace
+$ babeltrace2 /path/to/trace --debug-info
----
+
[role="term"]
----
$ babeltrace2 /path/to/trace \
- --debug-info-target-prefix=/tmp/tgt-root
+ --debug-info-target-prefix=/tmp/tgt-root
----
+
[role="term"]
----
* 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:
+
+
[role="term"]
----
-$ babeltrace2 /path/to/trace --output-format=text
-----
-+
-[role="term"]
-----
$ 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:
+
* 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 \
- --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 \
- --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
[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[]
-
-
-[[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).
+The order of the implicit component options documented in this
+subsection is not significant.
-'mm'::
- 2-digit minute.
+See <<examples,``EXAMPLES''>> for more examples.
-'ss'::
- 2-digit second.
-'nnnnnnnnn'::
- 9-digit nanosecond.
+== OPTIONS
-
-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.
+=== Explicit component creation
+
+See <<comp-create-expl,``Create explicit components''>> to learn how to
+use the following option.
-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' (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`::
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'::
+=== 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.
+
+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. 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'.
+ 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[]
+--
-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:
+=== Legacy options to create implicit components
+
+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`::
- 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`::
- 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`::
- Create an implicit compcls:src.ctf.lttng-live component. The
- position argument sets the manparam:source.ctf.lttng-live:url
- parameter of the component.
+ Use the compcls:source.ctf.lttng-live component class.
+
-Any other format for the positional argument is invalid.
-+
-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'::
- 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.
- 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`::
- 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.
+
-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`::
- 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]]
-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
- 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
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
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.
-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
- 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
- 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'::
- 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 `]`.
-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.
-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.
- 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
[[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.
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
+
--
`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.
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
- 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
-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
-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
- 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
- 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.
-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).
+
-Default: 100000 (100{nbsp}ms).
+Default: 100000 (100~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.
+ Enable the stream intersection mode.
+
-All the source components, <<comp-create-expl,explicit>> and
-<<comp-create-impl,implicit>>, must have classes which support the
-`babeltrace.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
---------
-.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-files.txt[]
+
include::common-cmd-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
+man:babeltrace2-intro(7),
man:babeltrace2(1),
-man:babeltrace2-run(1),
-man:babeltrace2-intro(7)
+man:babeltrace2-run(1)
projects / babeltrace.git / blobdiff