babeltrace2-plugin-utils \
babeltrace2-sink.ctf.fs \
babeltrace2-sink.text.pretty \
+ babeltrace2-sink.text.details \
babeltrace2-sink.utils.counter \
babeltrace2-sink.utils.dummy \
babeltrace2-source.ctf.fs \
babeltrace2-source.ctf.lttng-live \
- babeltrace2-source.text.dmesg
+ babeltrace2-source.text.dmesg \
+ babeltrace2-query-babeltrace.support-info \
+ babeltrace2-query-babeltrace.trace-infos
MAN1_NO_ASCIIDOC_NAMES =
MAN7_NO_ASCIIDOC_NAMES =
$(srcdir)/common-cmd-footer.txt \
$(srcdir)/common-cmd-info-options.txt \
$(srcdir)/common-cmd-params-format.txt \
- $(srcdir)/common-cmd-plugin-path.txt \
- $(srcdir)/common-common-compat-env.txt \
- $(srcdir)/common-ctf-plugin-env.txt \
+ $(srcdir)/common-common-env.txt \
$(srcdir)/common-footer.txt \
$(srcdir)/common-gen-options.txt \
$(srcdir)/common-lib-env.txt \
- $(srcdir)/common-plugin-path-options.txt \
- $(srcdir)/common-ppp-env.txt
+ $(srcdir)/common-see-babeltrace2-intro.txt \
+ $(srcdir)/common-convert-examples.txt \
+ $(srcdir)/common-log-levels.txt \
+ $(srcdir)/common-trimmer-time-format.txt
# config
ASCIIDOC_CONF = $(srcdir)/bt-asciidoc.conf
-= Babeltrace man pages
+// Render with Asciidoctor
+
+= Babeltrace{nbsp}2 manual pages
Philippe Proulx
-4 October 2017
+4 September 2019
+:toc:
-This directory contains the sources of the Babeltrace man pages.
+This directory contains the sources of the Babeltrace{nbsp}2 manual
+pages.
-The Babeltrace man pages are written in
-http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
+The Babeltrace{nbsp}2 manual pages are written in
+https://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to
DocBook (XML) using the `asciidoc` command, and finally to troff using
the appropriate DocBook XSL stylesheet (using the `xmlto` command).
== Naming
Main program::
- +__program__.1.txt+
+ `__program__.1.txt`
-`babeltrace2(1)` command::
- +babeltrace2-__command__.1.txt+
+Specific `babeltrace2(1)` command::
+ `babeltrace2-__command__.1.txt`
-Babeltrace introduction::
+Babeltrace{nbsp}2 introduction::
`babeltrace2-intro.7.txt`
-Babeltrace plugin::
- +babeltrace2-plugin-__plugin__.7.txt+
+Babeltrace{nbsp}2 plugin::
+ `babeltrace2-plugin-__plugin-name__.7.txt`
+
+Babeltrace{nbsp}2 component class::
+ `babeltrace2-__type__.__plugin-name__.__comp-cls-name__.7.txt`
-Babeltrace plugin's component class::
- +babeltrace2-__type__.__plugin__.__compcls__.7.txt+
+Babeltrace{nbsp}2 query object::
+ `babeltrace2-query-__query-object-name__.7.txt`
== Macros
AsciiDoc is configured with `bt-asciidoc.conf` which contains a few
-macro definitions used everywhere in the man page sources:
+macro definitions used everywhere in the manual page sources:
-+man:__page__(__section__)+::
- Use this macro to insert a link to another man page named
- +__page__+ in section +__section__+. In troff, the man page's name
- is rendered in bold.
+Other manual page::
++
+--
+`man:__page__(__section__)`::
+ Insert a link to another manual page named `__page__` in section
+ `__section__`. In troff, the manual page's name is rendered in bold.
+
Example: `man:babeltrace2-convert(1)`
+--
-+opt:__name__+::
- Use this macro to insert a link to the command-line option
- +__name__+ described in an _OPTIONS_ section in the same man page.
+Command-line option::
+
-Example: `opt:--verbose`, `opt:--color='WHEN'`
-
-+manopt:__page__(__section__):__name__+::
- Use this macro to insert a link to the command-line option
- +__name__+ described in the _OPTIONS_ section of another Babeltrace
- or LTTng man page named +__page__+ in section +__section__+.
+--
+`opt:__name__`::
+ Insert a link to the command-line option `__name__` described in the
+ _OPTIONS_ section in the same manual page.
+
-Example: `manopt:babeltrace2(1):--log-level`,
-+manopt:babeltrace2-convert(1):--component=\`source.ctf.fs`+
+Examples: `opt:--verbose`, `+opt:--color='WHEN'+`
-+nlopt:__name__+::
- Use this macro to write a command-line option named +__name__+
- without inserting a link. The option does not need to be described
- in the same man page.
+`manopt:__page__(__section__):__name__`::
+ Insert a link to the command-line option `__name__` described in the
+ _OPTIONS_ section of another Babeltrace{nbsp}2 or LTTng manual page
+ named `__page__` in section `__section__`.
+
-Example: `nlopt:--help`
+Examples: `manopt:babeltrace2(1):--log-level`,
+`+manopt:babeltrace2-convert(1):--component=pass:[`source.ctf.fs`]+`
-+param:__name__+::
- Use this macro to insert a link to the component initialization
- parameter named +__name__+ described in an _INITIALIZATION
- PARAMETERS_ section in the same man page.
+`nlopt:__name__`::
+ Write a command-line option named `__name__` without inserting a
+ link. The option does not need to be described in the same manual
+ page.
+
-Example: `param:begin`, `param:path='PATH'`
+Examples: `nlopt:--help`, `+nlopt:--log-level='LEVEL'+`
+--
-+manparam:__type__.__plug__.__compclsname__:__paramname__+::
- Use this macro to insert a link to the component initialization
- parameter +__paramname__+ described in the _INITIALIZATION
- PARAMETERS_ section of the man page of another Babeltrace component
- class. The component class has the type +__type__+, is found in the
- plugin named +__plug__+ and is named +__name__+.
+Component initialization or query parameter::
++
+--
+`param:__name__`::
+ Insert a link to the component initialization or query parameter
+ named `__name__` described in an _INITIALIZATION PARAMETERS_ or
+ _PARAMETERS_ section in the same manual page.
++
+Examples: `param:begin`, `+param:inputs='PATHS'+`
+
+`manparam:__type__.__plugin-name__.__comp-cls-name__:__param-name__`::
+ Insert a link to the component initialization or query parameter
+ `__param-name__` described in the _INITIALIZATION PARAMETERS_ or
+ _PARAMETERS_ section of the manual page of another Babeltrace{nbsp}2
+ component class. The component class has the type `__type__`, is
+ found in the plugin named `__plugin-name__`, and is named
+ `__comp-cls-name__`.
+
-Example: `manparam:filter.utils.trimmer:begin`,
-`manparam:source.ctf.fs:path`
+Examples: `manparam:filter.utils.trimmer:begin`,
+`manparam:source.ctf.fs:inputs`
-+nlparam:__name__+::
- Use this macro to write a component initialization parameter named
- +__name__+ without inserting a link. The parameter does not need to
- be described in the same man page.
+`nlparam:__name__`::
+ Write a component initialization or query parameter named `__name__`
+ without inserting a link. The parameter does not need to be
+ described in the same manual page.
+
Example: `nlparam:end`
-+compcls:__type__.__plug__.__name__+::
- Use this macro to write a component class specification. The
- component class has the type +__type__+, is found in the plugin
- named +__plug__+ and is named +__name__+.
+`qres:__name__`::
+ Insert a link to the query result object entry named `__name__`
+ described in a _RESULT OBJECT_ section in the same manual page.
++
+Examples: `qres:input`, `+qres:group='GROUP'+`
+
+`nlqres:__name__`::
+ Write a query result object entry named `__name__` without inserting
+ a link. The entry does not need to be described in the same manual
+ page.
++
+Example: `nlqres:group`
+
+`vtype:[__type__]`::
+ Write a value object type `__type__`.
++
+Examples: `vtype:[optional boolean]`, `vtype:[signed integer or string]`
+--
+
+Component class::
++
+--
+`compcls:__type__.__plugin-name__.__comp-cls-name__`::
+ Write a component class specification. The component class has the
+ type `__type__`, is found in the plugin named `__plugin-name__`, and
+ is named `__comp-cls-name__`.
++
+Examples: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
+--
+
+Text emphasis and replacement::
+
-Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer`
+--
+`:all:`::
+ Emphasize "`all`".
`:not:`::
- Use `:not:` to emphasize _not_.
+ Emphasize "`not`".
`:escstar:`::
- Use `:escstar:` to insert `\*` literally.
+ Insert `+\*+` literally.
`:esccomma:`::
- Use `:esccomma:` to insert `\,` literally.
+ Insert `+\,+` literally.
`:escdot:`::
- Use `:escdot:` to insert `\.` literally.
+ Insert `+\.+` literally.
+--
== Attributes
`manpagetype`::
- Each man page must set this attribute to the type (lowercase) of the
- man page: `program`, `command`, `plugin`, or `component class`. It's
- used in various included files to output a text that is more
- targeted.
+ Each manual page must set this attribute to the type (lowercase) of
+ the manual page: `program`, `command`, `plugin`, or `component
+ class`. It's used in various included files to output a text that is
+ more targeted.
`revdate`::
- Each man page should have its own revision date with the following
+ Each manual page must have its own revision date with the following
https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]:
_28 October 1987_.
+
-Make sure to update this date when you update a given man page. We are
-not generating the date automatically because we want the real last
-revision date in the man page, not the last build date.
+Make sure to update this date when you update a given manual page. We
+are not generating the date automatically because we want the real last
+revision date in the manual page, not the last build date.
Also see `asciidoc-attrs.conf` which is generated by `config.status`
from `asciidoc-attrs.conf.in`. This file contains fixed and
sources.
+== Internal links
+
+Internal links have no special formatting once converted to troff: it
+would look weird as there's no navigation in troff. We use them for
+cross-references since the manual page sources are also used to generate
+parts of the Babeltrace{nbsp}2 website.
+
+When an internal link's text is the name of a section (usually following
+"`see`"), put the section name between `pass:[``]` and `+''+` to outline
+it:
+
+----
+Lorem ipsum dolor sit amet (see <<sect-id,``The section name''>>),
+consectetur adipiscing elit.
+----
+
+This makes the manual page result look like this:
+
+----
+ Lorem ipsum dolor sit amet (see “The section name”), consectetur
+ adipiscing elit.
+----
+
+
== Style
Apply the recommendations of the
[attributes]
# default values
system_plugin_path="@LIBDIR@/babeltrace2/plugins"
+system_plugin_provider_path="@LIBDIR@/babeltrace2/plugin-providers"
babeltrace_version="@PACKAGE_VERSION@"
enable_debug_info="@ENABLE_DEBUG_INFO_VAL@"
+defrdport=5344
-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)
-babeltrace2-filter.lttng-utils.debug-info(7)
-===========================================
+= babeltrace2-filter.lttng-utils.debug-info(7)
:manpagetype: component class
-:revdate: 5 October 2017
-:comp: compcls:filter.lttng-utils.debug-info
+:revdate: 14 September 2019
+:compcls: compcls:filter.lttng-utils.debug-info
:defdebuginfoname: `debug_info`
-NAME
-----
-babeltrace2-filter.lttng-utils.debug-info - Babeltrace's debugging
+== NAME
+
+babeltrace2-filter.lttng-utils.debug-info - Babeltrace 2's debugging
information filter component class for LTTng traces
-DESCRIPTION
------------
-The Babeltrace {comp} component class, provided by the the
-man:babeltrace2-plugin-lttng-utils(7) plugin, once instantiated, receives
-events from http://lttng.org/[LTTng] traces and creates new ones
-which are copies of the original ones with extra debugging information
-when it's available and possible.
-
-A {comp} component uses the LTTng state dump events as well as the event
-context's `ip` (instruction pointer) field to locate and read the
-corresponding debugging information. The component can find the extra
-debugging information in an executable file or in a directory containing
-debugging information created by the compiler.
-
-The new events contain the exact same fields as the original ones and,
-when possible, a new event context's structure field (besides the `ip`
-field) named {defdebuginfoname} by default. This structure field
-contains the following fields:
-
-`bin` (string field)::
- Executable path or name followed by `@ADDR` or `+ADDR`, where
- `ADDR` is the address where it was loaded while being traced.
- `@ADDR` means `ADDR` is an absolute address, and `+ADDR` means
- `ADDR` is a relative address.
+== DESCRIPTION
+
+A Babeltrace~2 {compcls} message iterator creates and emits copies of
+upstream messages, augmenting LTTng event messages with debugging
+information when it's available and possible.
+
+----
+Messages without
+debugging information
+ |
+ | +----------------------------+
+ | | flt.lttng-utils.debug-info |
+ | | |
+ '->@ in out @--> Messages with
+ +----------------------------+ debugging information
+----
+
+include::common-see-babeltrace2-intro.txt[]
+
+A {compcls} message iterator uses the LTTng state dump events as well as
+the event common context's `ip` (instruction pointer) and `vpid`
+(process ID) fields to locate and read the corresponding debugging
+information. The message iterator can find the extra debugging
+information in an executable file or in a directory containing debugging
+information which the compiler creates.
+
+The new LTTng events (copies of the original ones with added debugging
+information) contain, when possible, a new event common context's
+structure field (besides the `ip` field) named {defdebuginfoname} by
+default (you can use the param:debug-info-field-name parameter to choose
+another name). This structure field contains the following fields:
+
+`bin` vtype:[string]::
+ Executable path or name followed with `@ADDR` or `+ADDR`, where
+ `ADDR` is the address (hexadecimal) where it was loaded while being
+ traced.
++
+`@ADDR` means `ADDR` is an absolute address, and `+ADDR` means `ADDR` is
+a relative address.
+
-Example: `my-program@0x401040`.
+Examples: `my-program@0x4b7fdd23`, `my-program+0x18d7c`.
-[[field-func]]`func` (string field)::
- Function name followed by `+OFFSET`, where `OFFSET` is the
- offset from the beginning of the function symbol in the executable
- file.
+[[field-func]]`func` vtype:[string]::
+ Function name followed with `+OFFSET`, where `OFFSET` is the offset
+ (hexadecimal) from the beginning of the function symbol in the
+ executable file.
+
Example: `load_user_config+0x194`.
-[[field-src]]`src` (string field)::
- Source file path or name followed by `:LINE`, where `LINE` is the
+[[field-src]]`src` vtype:[string]::
+ Source file path or name followed with `:LINE`, where `LINE` is the
line number in this source file at which the event occured.
+
Example: `user-config.c:1025`.
-Any of those the previous fields can be an empty string if the
-debugging information was not available for the analyzed original
-LTTng event.
+Any of the previous fields can be an empty string if the debugging
+information was not available for the analyzed original LTTng event.
-When a filter component creates a new event with debugging
-information, it discards the original event. If the component receives a
-non-LTTng event, the component moves the event to its output port
-without alteration.
+A {compcls} message iterator systematically copies the upstream
+messages, but it only augments compatible LTTng event classes. This
+means that the message iterator copies messages of non-LTTng trace (see
+<<lttng-prereq,``LTTng prerequisites''>>) without alteration.
-Compile an executable for debugging information analysis
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-With GCC or Clang, you should compile the program or library source
+=== Compile an executable for debugging information analysis
+
+With GCC or Clang, you need to compile the program or library source
files in debug mode with the nlopt:-g option. This option makes the
compiler generate debugging information in the operating system's native
-format. This format is recognized by a {comp} component: it can
-translate the instruction pointer field of an event's context to a
-source file and line number, along with the name of the surrounding
+format. This format is recognized by a {compcls} component: it can
+translate the instruction pointer field of an event's common context to
+a source file and line number, along with the name of the surrounding
function.
-NOTE: This component class only supports the debugging information in
-DWARF format, version{nbsp}2 or later. Use the nlopt:-gdwarf or
+IMPORTANT: This component class only supports the debugging information
+in DWARF format, version~2 or later. Use the nlopt:-gdwarf or
nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler
options to explicitly generate DWARF debugging information.
If you don't compile the executable's source files with the nlopt:-g
option or with an equivalent option, no DWARF information is available:
-the component uses ELF symbols from the executable file instead. In this
-case, the events that the component creates do not contain the source
-file and line number (<<field-src,`src` field>>), but only the name of
-the nearest function symbol with an offset in bytes to the location in
-the executable from which the LTTng event occured (<<field-func,`func`
-field>>).
+the message iterator uses ELF symbols from the executable file instead.
+In this case, the events that the message iterator creates do not
+contain the source file and line number (see the <<field-src,`src`
+field>>), but only the name of the nearest function symbol with an
+offset in bytes to the location in the executable from which the LTTng
+event occured (see the <<field-func,`func` field>>).
If the executable file has neither ELF symbols nor DWARF information,
-the {comp} component cannot map the event to
-its source location: it emits the original LTTng event which has no
-special {defdebuginfoname} context field.
+the {compcls} message iterator cannot map the event to its source
+location: the message iterator still copies the upstream messages but
+without altering them.
+
+[[lttng-prereq]]
+=== LTTng prerequisites
-LTTng prerequisites
-~~~~~~~~~~~~~~~~~~~
-A {comp} component can only analyze user space events generated by
-http://lttng.org[LTTng]{nbsp}2.8.0 or later.
+A {compcls} message iterator can only analyze user space events which
+https://lttng.org[LTTng]~2.8.0 or later generates.
To get debugging information for LTTng-UST events which occur in
executables and libraries which the system's loader loads (what
--
-Separate debugging information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is possible to store DWARF debugging information outside the
-executable itself, whether it is to reduce the executable's file size,
-or simply to facilitate the sharing of the debugging information.
+=== Separate debugging information
+
+You can store DWARF debugging information outside the executable itself,
+whether it is to reduce the executable's file size or simply to
+facilitate sharing the debugging information.
This is usually achieved via one of two mechanisms, namely _build ID_
and _debug link_. Their use and operation is described in the
https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging
Information in Separate Files] section of GDB's documentation.
-A {comp} component can find separate debugging information files
-automatically, as long as they meet the requirements stated in this man
-page.
+A {compcls} message iterator can find separate debugging information
+files automatically, as long as they meet the requirements stated in
+this manual page.
The debugging information lookup order is the same as GDB's, namely:
. In the various possible debug link locations.
-The component uses the first debugging information file that it finds.
+The message iterator uses the first debugging information file that it
+finds.
-You can use the param:deubg-info-dir initialization parameter to
+You can use the param:debug-info-dir initialization parameter to
override the default `/usr/lib/debug` directory used in the build ID and
debug link methods.
debugging information in multiple directories.
-Target prefix
-~~~~~~~~~~~~~
-The debugging information analysis that a {comp} component performs uses
-the paths to the executables as collected during tracing as the default
-mechanism to resolve DWARF and ELF information.
+=== Target prefix
+
+The debugging information analysis that a {compcls} message iterator
+performs uses the paths to the executables as collected during tracing
+as the default mechanism to resolve DWARF and ELF information.
If the trace was recorded on a separate machine, however, you can use
the param:target-prefix parameter to specify a prefix directory, that
For example, if an instrumented executable's path is `/usr/bin/foo` on
the target system, you can place this file at
-`/home/user/target/usr/bin/foo` on the system on which you use the
-component. In this case, the target prefix to use is
+`/home/user/target/usr/bin/foo` on the system on which you use a
+{compcls} component. In this case, the target prefix to use is
`/home/user/target`.
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
+== INITIALIZATION PARAMETERS
-param:debug-info-dir='DIR' (string)::
+param:debug-info-dir='DIR' vtype:[optional string]::
Use 'DIR' as the directory from which to load debugging information
with the build ID and debug link methods instead of
`/usr/lib/debug`.
-param:debug-info-field-name='NAME' (string)::
- Name the debugging information structure field in the context of
- the created events 'NAME' instead of the default {defdebuginfoname}.
+param:debug-info-field-name='NAME' vtype:[optional string]::
+ Name the debugging information structure field in the common context
+ of the created events 'NAME' instead of the default
+ {defdebuginfoname}.
-param:full-path=`yes` (boolean)::
+param:full-path=`yes` vtype:[optional boolean]::
Use the full path when writing the executable name (`bin`) and
source file name (`src`) fields in the {defdebuginfoname} context
field of the created events.
-param:target-prefix='DIR' (string)::
+param:target-prefix='DIR' vtype:[optional string]::
Use 'DIR' as the root directory of the target file system instead of
`/`.
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications to augment with debugging information.
+== PORTS
+----
++----------------------------+
+| flt.lttng-utils.debug-info |
+| |
+@ in out @
++----------------------------+
+----
-Output
-~~~~~~
-`out`::
- Single output port to which the component sends the augmented
- or unaltered notifications.
+=== Input
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+`in`::
+ Single input port.
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+=== Output
-`BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
+`out`::
+ Single output port.
include::common-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
+man:babeltrace2-intro(7),
man:babeltrace2-plugin-lttng-utils(7),
man:lttng(1),
-man:lttng-add-context(1),
-man:babeltrace2-intro(7)
+man:lttng-add-context(1)
-babeltrace2-filter.utils.muxer(7)
-================================
+= babeltrace2-filter.utils.muxer(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
+== NAME
+
+babeltrace2-filter.utils.muxer - Babeltrace 2's message muxer filter
+component class
+
+
+== DESCRIPTION
+
+A Babeltrace~2 compcls:filter.utils.muxer message iterator muxes
+the messages that it consumes from one or more upstream message
+iterators into a linear sequence of messages ordered by time.
+
+----
+ +-----------------+
+ | flt.utils.muxer |
+ | |
+Messages -->@ in0 out @--> Sorted messages
+Messages -->@ in1 |
+Messages -->@ in2 |
+ @ in3 |
+ +-----------------+
----
-babeltrace2-filter.utils.muxer - Babeltrace's notification multiplexer
-filter component class
+include::common-see-babeltrace2-intro.txt[]
-DESCRIPTION
------------
-The Babeltrace compcls:filter.utils.muxer component class, provided by
-the man:babeltrace2-plugin-utils(7) plugin, once instantiated,
-multiplexes the notifications that it receives from one or more input
-ports into a linear sequence of events ordered by time on its output
-port.
+A compcls:filter.utils.muxer message iterator does not alter the
+messages it consumes: it only sorts them.
-A compcls:filter.utils.muxer component does not alter the notifications
-it receives: it only sorts them.
+The message iterator creates one upstream message iterator per connected
+input port.
-A compcls:filter.utils.muxer component can only work on notifications in
-which the clock value with the highest priority has an absolute clock
-class. You can use the param:assume-absolute-clock-classes parameter to
-make the component assume that all clock classes are absolute. In this
-case, you must ensure that, when more than one clock class exists, they
-are correlatable.
+NOTE: To support muxing messages with different default clock classes,
+the message iterator converts the message times to nanoseconds from the
+common origin (Unix epoch, for example). This means that the resulting
+message sequence could be incorrect if one or more clock classes have a
+frequency which is greater than 1~GHz.
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
+== PORTS
+
+----
++-----------------+
+| flt.utils.muxer |
+| |
+@ in0 out @
+@ ... |
++-----------------+
+----
-param:assume-absolute-clock-classes=`yes` (boolean)::
- Assume that all clock classes are absolute.
+=== Input
-PORTS
------
-Input
-~~~~~
`inN`, where `N` is a decimal integer starting at 0::
- Input port from which the component receives notifications to
- multiplex.
+ Input port on which a compcls:filter.utils.muxer message iterator
+ creates an upstream message iterator to consumes messages from.
+
-When you create the component, its only input port is
+When the component is initialized, its only input port is
`in0`. When you connect the `in0` port, the component creates
-the `in1` input port, and so on. If you disconnect an input port,
-the component does not create a new input port: the disconnected
-input port is now available for a new connection.
+the `in1` input port, and so on.
+
-In other words, a compcls:filter.utils.muxer component always makes sure
-that it has at least one available input port.
-
-
-Output
-~~~~~~
-`out`::
- Single output port to which the component sends the
- sorted notifications.
+In other words, a compcls:filter.utils.muxer component always has an
+available input port.
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+=== Output
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-`BABELTRACE_FLT_UTILS_MUXER_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
+`out`::
+ Single output port.
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-utils(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-utils(7)
-babeltrace2-filter.utils.trimmer(7)
-==================================
+= babeltrace2-filter.utils.trimmer(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-filter.utils.trimmer - Babeltrace's trimmer filter
-component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:filter.utils.trimmer component class, provided by
-the man:babeltrace2-plugin-utils(7) plugin, once instantiated, discards
-all the received events with a time less than a given beginning time and
-greater than a given end time. It effectively ``cuts'', or trims traces.
-
-A compcls:filter.utils.trimmer component modifies the `timestamp_begin`
-and `timestamp_end` fields of the packet contexts it receives to match
-the beggining and end times of the trimming range when needed.
-
-The component used a notification's clock value with the highest
-priority to decide whether to discard it or not.
-
+== NAME
-[[time-param-fmt]]
-Time parameter format
-~~~~~~~~~~~~~~~~~~~~~
-The format of the param:begin and param:end parameters is:
+babeltrace2-filter.utils.trimmer - Babeltrace 2's trimmer filter
+component class
-[verse]
-$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
-'YYYY'::
- 4-digit year.
+== DESCRIPTION
-'MM'::
- 2-digit month (January is `01`).
+A Babeltrace~2 compcls:filter.utils.trimmer message iterator
+discards all the consumed messages with a time less than a given
+beginning time and greater than a given end time. It effectively
+``cuts'', or trims trace streams.
-'DD'::
- 2-digit day.
+----
+ +-------------------+
+ | flt.utils.trimmer |
+ | |
+Messages -->@ in out @--> Less messages
+ +-------------------+
+----
-'hh'::
- 2-digit hour (24-hour format).
+include::common-see-babeltrace2-intro.txt[]
-'mm'::
- 2-digit minute.
+A compcls:filter.utils.trimmer message iterator makes its upstream
+message iterator seek the configured beginning time (see the param:begin
+parameter) before it starts to consume messages. This seeking operation
+can have an effect on the times of stream beginning, packet beginning,
+discarded events, and discarded packets messages so that they fall
+within the configured trimming time range.
-'ss'::
- 2-digit second.
+As such, when a compcls:filter.utils.trimmer message iterator consumes a
+message of which the time is greater than the configured end time (see
+the param:end parameter), it can alter the time of stream end, packet
+end, discarded events, and discarded packets messages so that they fall
+within the configured trimming time range.
-'nnnnnnnnn'::
- 9-digit nanosecond.
+A compcls:filter.utils.trimmer message iterator requires that all the
+upstream messages it consumes have times, except for stream beginning
+and end messages, returning an error status otherwise.
-INITIALIZATION PARAMETERS
--------------------------
-You must specify at least one of the param:begin and param:end
-parameters.
+== INITIALIZATION PARAMETERS
-param:begin='BEGIN' (string or integer)::
- Set the trimmer's beginning time to 'BEGIN'.
+param:begin='TIME' vtype:[optional string or signed integer]::
+ Set the trimming time range's beginning time to 'TIME'.
+
-If 'BEGIN' is a string, see <<time-param-fmt,Time parameter format>> for
-its format. If 'BEGIN' is an integer, it is the number of nanoseconds
-since Epoch.
+If 'TIME' is a string, see below for its format. If 'TIME' is a signed
+integer, the component converts it to a string and treats it as such.
+
If you don't specify this parameter, the component discards no events
-until the end of the trimming range.
-
-param:clock-gmt=`yes` (boolean)::
- Set the time zone of the param:begin and param:end parameters
- to GMT instead of the local time zone.
+until the end of the trimming time range.
++
+The format of 'TIME' when it's a string is one of:
++
+--
+include::common-trimmer-time-format.txt[]
+--
++
+If 'TIME' has no date information, then the message iterator uses the
+first upstream message's time to determine the date.
-param:end='END' (string or integer)::
- Set the trimmer's end time to 'END'.
+param:end='TIME' vtype:[optional string or signed integer]::
+ Set the trimming time range's end time to 'TIME'.
+
-If 'END' is a string, see <<time-param-fmt,Time parameter format>> for
-its format. If 'END' is an integer, it is the number of nanoseconds
-since Epoch.
+If 'TIME' is a string, see the param:begin parameter for its format. If
+'TIME' is a signed integer, the component converts it to a string and
+treats it as such.
+
If you don't specify this parameter, the component discards no events
-from the beginning of the trimming range.
+from the beginning of the trimming time range.
+param:gmt=`yes` vtype:[optional boolean]::
+ Set the time zone of the param:begin and param:end parameters
+ to GMT instead of the local time zone.
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications.
+== PORTS
+
+----
++-------------------+
+| flt.utils.trimmer |
+| |
+@ in out @
++-------------------+
+----
-Output
-~~~~~~
-`out`::
- Single output port to which the components sends the notifications
- of which the time is in the trimming range.
+=== Input
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+`in`::
+ Single input port.
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+=== Output
-`BABELTRACE_FLT_UTILS_TRIMMER_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
+`out`::
+ Single output port.
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-utils(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-utils(7)
-babeltrace2-help(1)
-==================
+= babeltrace2-help(1)
:manpagetype: command
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-help - Get help for a Babeltrace plugin or component class
+== NAME
+
+babeltrace2-help - Get help for a Babeltrace 2 plugin or component class
+
+
+== SYNOPSIS
+
+Get help for a Babeltrace~2 plugin:
+
+[verse]
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *help* 'PLUGIN-NAME'
+Get help for a Babeltrace~2 component class:
-SYNOPSIS
---------
[verse]
-*babeltrace2 help* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- ('PLUGIN' | 'TYPE.PLUGIN.COMPCLS')
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *help*
+ 'COMP-CLS-TYPE'.'PLUGIN-NAME'.'COMP-CLS-NAME'
-DESCRIPTION
------------
-The `help` command prints the details and help text of either the plugin
-'PLUGIN' or the specific component class 'TYPE.PLUGIN.COMPCLS'.
+== DESCRIPTION
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+The `help` command prints the details and help text of either the
+Babeltrace~2 plugin named 'PLUGIN-NAME' or the specific component
+class of type 'COMP-CLS-TYPE' named 'COMP-CLS-NAME' found in the plugin
+named 'PLUGIN-NAME'.
-The available values for 'TYPE' are:
+include::common-see-babeltrace2-intro.txt[]
-`source` or `src`::
+The available values for 'COMP-CLS-TYPE' are:
+
+`source`::
+`src`::
Source component class.
-`filter` or `flt`::
+`filter`::
+`flt`::
Filter component class.
`sink`::
Sink component class.
-See <<examples,EXAMPLES>> for usage examples.
-
+See <<examples,``EXAMPLES''>> for usage examples.
-include::common-cmd-plugin-path.txt[]
+== OPTIONS
-OPTIONS
--------
include::common-gen-options.txt[]
-include::common-plugin-path-options.txt[]
-
include::common-cmd-info-options.txt[]
[[examples]]
-EXAMPLES
---------
+== EXAMPLES
+
.Get help for a plugin and all its component classes.
====
[role="term"]
----
-$ babeltrace2 help my-plugin
+$ babeltrace2 help ctf
----
====
====
[role="term"]
----
-$ babeltrace2 help src.my-plugin.my-source
+$ babeltrace2 help source.ctf.fs
----
====
====
[role="term"]
----
-$ babeltrace2 help sink.my-plugin.my-sink
+$ babeltrace2 help sink.text.pretty
----
====
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-list-plugins(1)
-man:babeltrace2-intro(7)
-babeltrace2-intro(7)
-===================
-:manpagetype: man page
-:revdate: 5 October 2017
+= babeltrace2-intro(7)
+:manpagetype: manual page
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-intro - Introduction to Babeltrace
+== NAME
+
+babeltrace2-intro - Introduction to Babeltrace 2
+
+== DESCRIPTION
-DESCRIPTION
------------
-This man page is an introduction to the Babeltrace project.
+This manual page is an introduction to the Babeltrace~2 project.
-The <<what-is,WHAT IS BABELTRACE?>> section lists the parts of the
-project and shows the major changes from Babeltrace{nbsp}1 to
-Babeltrace{nbsp}2 while the <<concepts,BABELTRACE CONCEPTS>> section
-defines the core concepts of Babeltrace.
+The <<what-is,``WHAT IS BABELTRACE~2?''>> section describes the
+parts of the project and shows the major changes from Babeltrace~1
+to Babeltrace~2 while the <<concepts,``BABELTRACE~2
+CONCEPTS''>> section defines the core concepts of Babeltrace~2.
-The <<graph-repr,TRACE PROCESSING GRAPH REPRESENTATION>> section shows
-how some <<concepts,concepts>> are visually represented in other
-Babeltrace man pages.
+The <<graph-repr,``TRACE PROCESSING GRAPH REPRESENTATION''>> section
+shows how some <<concepts,concepts>> are visually represented in other
+Babeltrace~2 manual pages.
[[what-is]]
-WHAT IS BABELTRACE?
--------------------
-Babeltrace is an open-source software project of which the purpose is
-to process or convert
+== WHAT IS BABELTRACE~2?
+
+Babeltrace~2 is an open-source software project of which the
+purpose is to process or convert
https://en.wikipedia.org/wiki/Tracing_(software)[traces].
-The Babeltrace project includes the following parts:
+The Babeltrace~2 project includes the following parts:
-[[libbabeltrace2]]Babeltrace library (libbabeltrace2)::
+[[libbabeltrace2]]Babeltrace~2 library (libbabeltrace2)::
A shared library with a C API.
+
With libbabeltrace2, you can programmatically create <<plugin,plugins>>
-and <<comp-cls,component classes>>, build and run <<graph,processing
-graphs>>, and more (see the <<concepts,BABELTRACE CONCEPTS>> section for
-more details about those concepts). All the other Babeltrace parts rely
-on this library.
+and <<comp-cls,component classes>>, build and run <<graph,trace
+processing graphs>>, and more (see the <<concepts,``BABELTRACE~2
+CONCEPTS''>> section for more details about those concepts).
++
+All the other Babeltrace~2 parts rely on this library.
-[[babeltrace2-1]]`babeltrace2` command::
+[[babeltrace2]]`babeltrace2` command-line program::
A command-line interface which uses libbabeltrace2 to load plugins,
- create a trace processing graph, create components, and run the
- graph.
+ create a trace processing graph, create <<comp,components>>, connect
+ their <<port,ports>> correctly, and run the graph.
+
-You can also use `babeltrace2` to list the available plugins or to query
-an object from a component class.
+You can also use `babeltrace2` to list the available plugins or to
+<<query,query>> an object from a component class.
+
See man:babeltrace2(1).
-[[python-bindings]]Babeltrace Python bindings::
- A Python{nbsp}3 package which offers a Pythonic interface of
+[[python-bindings]]Babeltrace~2 Python bindings::
+ A Python~3 package (`bt2`) which offers a Pythonic interface of
libbabeltrace2.
+
-You can perform the same operations which are available in libbabeltrace2
-with the Python bindings, but in a really easier way and with less code.
+You can perform the same operations which are available in
+libbabeltrace2 with the Python bindings, but more conveniently and with
+less code. However, the Python bindings are less performant than
+libbabeltrace2.
-Babeltrace project's plugins::
- The Babeltrace <<plugin,plugins>> shipped with the project.
+Babeltrace~2 project's plugins::
+ The Babeltrace
~2 <<plugin,plugins>> shipped with the project.
+
-Those plugins are not special, in that they only rely on libbabeltrace2
-and you don't need them to use libbabeltrace2, man:babeltrace2(1), or the
-Python bindings.
+Those plugins are not special in that they only rely on libbabeltrace2
+and you don't need them to use libbabeltrace2, man:babeltrace2(1), or
+the Python bindings. However, the project's plugins provide many widely
+used trace format encoders/decoders as well as common <<graph,trace
+processing graph>> utilities.
+
-The Babeltrace project's plugins are:
+The Babeltrace~2 project's plugins are:
+
--
`ctf`::
- Common Trace Format input/output, including the LTTng live source.
+ https://diamon.org/ctf/[Common Trace Format] (CTF) input/output,
+ including the LTTng live source.
+
See man:babeltrace2-plugin-ctf(7).
`lttng-utils`::
- Graph utilities specific to http://lttng.org/[LTTng] traces.
+ Graph utilities specific to https://lttng.org/[LTTng] traces.
+
See man:babeltrace2-plugin-lttng-utils(7).
`text`::
- Text input/output.
+ Plain text input/output.
+
See man:babeltrace2-plugin-text(7).
`utils`::
- Graph utilities (muxer, trimmer, counter, dummy sink).
+ Common graph utilities (muxer, trimmer, counter, dummy sink).
+
See man:babeltrace2-plugin-utils(7).
--
-Python plugin provider::
- A shared library which libbabeltrace2 tries to load to add support
- for Babeltrace plugins written in Python.
-+
-The package you use to write a Python Babeltrace plugin is the one
-provided by the Python bindings.
+=== Changes since Babeltrace~1
-Changes since Babeltrace{nbsp}1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-This man page is an introduction to Babeltrace{nbsp}2, a rewrite of
-Babeltrace{nbsp}1 with a focus on extensibility and flexibility.
+This manual page is an introduction to Babeltrace~2, a rewrite of
+Babeltrace~1 with a focus on extensibility, flexibility, and
+interoperability.
-Babeltrace{nbsp}1 exists since 2010. The major improvements brought by
-Babeltrace{nbsp}2 are:
+Babeltrace~1 exists since 2010. The major improvements brought by
+Babeltrace~2 are:
-* Full plugin support: any user can distribute a Babeltrace plugin and,
- as long as <<libbabeltrace2,libbabeltrace2>> finds it, any application
- linked to libbabeltrace2 can load it and use it.
+* Full plugin support: any user can distribute a Babeltrace~2
+ plugin and, as long as <<libbabeltrace2,libbabeltrace2>> finds it, any
+ application linked to libbabeltrace2 can load it and use it.
+
-Plugins are not just input and output formats: they provide source,
-filter, and sink <<comp-cls,component classes>> so that you can connect
-specialized, reusable components together in a graph to create a
-customized trace conversion or analysis device.
+Plugins are not just trace format encoders and decoders: they provide
+source, filter, and sink <<comp-cls,component classes>> so that you can
+connect specialized, reusable components together in a trace processing
+graph to create a customized trace conversion or analysis device.
-* In order to support user components, all the objects of libbabeltrace2
- have a reference count. The possible reference cycles are handled
- internally so that the library's API is clean and predictable. The two
- reference counting functions, `bt_get()` and `bt_put()`, are all you
- need to manage the lifetime of any Babeltrace object.
+* In order to support user components, many of the objects of
+ libbabeltrace2 have a reference count. The possible reference cycles
+ are handled internally so that the library's API is clean and
+ predictable.
++
+Objects which are often used on the "fast path" (for example, events,
+fields, and clock snapshots) are unique: they have no reference count.
-* All the parts of the Babeltrace project run on the major operating
- systems, including Windows and macOS.
+* All the parts of the Babeltrace~2 project run on the major
+ operating systems, including Windows and macOS.
[[concepts]]
-BABELTRACE CONCEPTS
--------------------
-This section defines the main concepts of the Babeltrace project. These
-concepts translate into types and functions in
+== BABELTRACE~2 CONCEPTS
+
+This section defines the main concepts of the Babeltrace~2 project.
+
+These concepts translate into types and functions in
<<libbabeltrace2,libbabeltrace2>> and its <<python-bindings,Python
bindings>>, but also as command-line actions and options in the
-<<babeltrace2-1,`babeltrace2` command>>. The other Babeltrace man pages
-assume that you are familiar with the following definitions.
+<<babeltrace2,`babeltrace2` program>>. The other Babeltrace~2
+manual pages assume that you are familiar with the following
+definitions.
-Some Babeltrace concepts are interdependent: it is normal to jump from
-one definition to another to understand the big picture.
+Some Babeltrace~2 concepts are interdependent: it is normal to jump
+from one definition to another to understand the big picture.
[[comp-cls]]Component class::
- A reusable class from which you can instantiate one or more
- <<comp,component>> instances.
+ A reusable class which you can instantiate as one or more
+ <<comp,components>> within a <<graph,trace processing graph>>.
+
-There are three types of component classes used to instantiate the three
-types of components (source, filter, and sink).
+There are three types of component classes used to create the three
+types of components: source, filter, and sink.
+
-A component class provides methods, one of which is an initialization
+A component class implements methods, one of which is an initialization
method, or constructor, to create a component. You pass _initialization
parameters_ to this method to customize the created component. For
-example, the initialization method of the compcls:src.ctf.fs component
-class accepts a mandatory manparam:source.ctf.fs:path parameter which is
-the file system path to the trace(s). It also accepts an optional
-manparam:source.ctf.fs:clock-class-offset-ns parameter which is an
-offset, in nanoseconds, to add to all the clock classes found in the
-traces's metadata.
+example, the initialization method of the compcls:source.ctf.fs
+component class accepts a mandatory manparam:source.ctf.fs:inputs
+parameter which is an array of file system path(s) to the CTF trace(s).
+It also accepts an optional manparam:source.ctf.fs:clock-class-offset-ns
+parameter which is an offset, in nanoseconds, to add to all the clock
+classes (descriptors of stream clocks) found in the traces's metadata.
++
+A component class can have a description and a help text.
[[comp]]Component::
A node within a <<graph,trace processing graph>>.
+
--
Source component::
- An input component which produces <<notif,notifications>>.
+ An input component which produces <<msg,messages>>.
+
-Examples: CTF files input, log file input, LTTng-live input, random
+Examples: CTF files input, log file input, LTTng live input, random
event generator.
Filter component::
- An intermediate component which can discard the notifications it
- receives, transform them, augment them, sort them, or create new
- ones.
+ An intermediate component which can transform the messages it
+ consumes, augment them, sort them, discard them, or create new ones.
+
-Examples: filter which removes notifications based on an expression,
-filter which adds debugging information to selected events, notification
-multiplexer, trace trimmer.
+Examples: filter which removes messages based on an expression,
+filter which adds debugging information to selected events, message
+muxer, trace trimmer.
Sink component::
- An output component which consumes notifications and usually writes
- them to one or more formatted files.
+ An output component which consumes messages and usually writes them
+ to one or more formatted files.
+
-Examples: log file output, CTF files output, text output on the
-console.
+Examples: log file output, CTF files output, pretty-printed plain text
+output.
--
+
Components are connected together within a <<graph,trace processing
both.
+
A component is the instance of a <<comp-cls,component class>>. The terms
-_component_ and _component instance_ are equivalent.
+_component_ and _component class instance_ are equivalent.
+
Within a trace processing graph, each component has a unique name. This
is not the name of its component class, but an instance name. If `human`
-is a component class name, than `John` could be a component name.
+is a component class name, than `Nancy` and `John` could be component
+names.
++
+Once a <<graph,graph>> is configured (the first time it runs), you
+cannot add components to it for the remaining graph's lifetime.
[[port]]Port::
A connection point, on a <<comp,component>>, from which are sent or
- to which are received <<notif,notifications>> when the <<graph,trace
- processing graph>> is running.
+ where are received <<msg,messages>> when the <<graph,trace
+ processing graph>> runs.
+
-An output port is where notifications are sent. An input port is where
-notifications are received. Source components have output ports, sink
+An output port is from where messages are sent. An input port is where
+messages are received. Source components have output ports, sink
components have input ports, and filter components have both.
+
-An output port can only be connected to a single input port at a given
-time.
+You can only connect an output port to a single input port.
+
-A filter or sink component receiving notifications from its input ports
-is said to _consume_ notifications.
+All ports do not need to be connected.
++
+A filter or sink component receiving messages from its input ports
+is said to _consume_ messages.
+
The link between an output port and input port is a <<conn,connection>>.
+
-A component can dynamically add and remove ports while a graph is
-running. For example, a compcls:filter.utils.muxer component always
-makes sure that it has at least one available input port.
+Once a <<graph,graph>> is configured (the first time it runs), you
+cannot connect ports for the remaining graph's lifetime.
[[conn]]Connection::
The link between an output <<port,port>> and an input port through
- which <<notif,notifications>> flow when a <<graph,trace processing
- graph>> is running.
+ which <<msg,messages>> flow when a <<graph,trace processing
+ graph>> runs.
+
+[[msg-iter]]Message iterator::
+ An iterator on an input <<port,port>> of which the returned elements
+ are <<msg,messages>>.
++
+A <<comp,component>> or another message iterator can create many message
+iterators on a single input port, before or while the <<graph,trace
+processing graph>> runs.
-[[notif]]Notification::
- An atomic element sent from an output <<port,port>> to an
- input port.
+[[msg]]Message::
+ The element of a <<msg-iter,message iterator>>.
++
+Messages flow from output <<port,ports>> to input ports.
+
-A source <<comp,component>> produces notifications, while a sink
-component consumes them. A filter component can both consume and
-produce notifications.
+A source <<comp,component>> <<msg-iter,message iterator>> produces
+messages, while a sink component consumes them. A filter component
+message iterator can both consume and produce messages.
+
-The main types of notifications are:
+The main types of messages are:
+
--
Event::
- A trace event record within a packet.
+ A trace event record within a packet or within a stream.
Packet beginning::
The beginning of a packet within a stream.
+
-A packet is a container of events.
+A packet is a conceptual container of events.
Packet end::
The end of a packet within a stream.
Stream beginning::
The beginning of a stream.
+
-A stream is a container of packets.
+A stream is a conceptual container of packets and/or events.
+
-Usually, a given source component's output port sends packet and
-event notifications which belong to a single stream.
+Usually, a given source component's output port sends packet and event
+messages which belong to a single stream, but it's not required.
Stream end::
The end of a stream.
[[graph]]Trace processing graph::
A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where
- nodes are <<comp,components>> and <<notif,notifications>> flow from
+ nodes are <<comp,components>> and <<msg,messages>> flow from
output <<port,ports>> to input ports.
+
You can build a trace processing graph with
-<<libbabeltrace2,libbabeltrace2>>, with the <<python-bindings,Babeltrace
-Python bindings>>, or with the man:babeltrace2-run(1) and
-man:babeltrace2-convert(1) commands.
+<<libbabeltrace2,libbabeltrace2>>, with the
+<<python-bindings,Babeltrace~2 Python bindings>>, or with the
+man:babeltrace2-run(1) and man:babeltrace2-convert(1) CLI commands.
+
-When you _run_ a trace processing graph, the sink components consume
-notifications from their input ports, making all the graph's components
-work one notification at a time to perform the trace conversion or
-analysis.
+When a trace processing graph _runs_, the sink components consume
+messages from their input ports, making all the graph's
+<<msg-iter,message iterators>> work one message at a time to perform the
+trace conversion or analysis duty.
[[plugin]]Plugin::
- A container of <<comp-cls,component classes>> as a shared library.
+ A container, or package, of <<comp-cls,component classes>> as a
+ shared library or Python module.
+
Each component class within a plugin has a type (source, filter, or
sink) and a name. The type and name pair is unique within a given
plugin.
+
-<<libbabeltrace2,libbabeltrace2>> can load a plugin (`.so` or `.dll` file)
-at run time: the result is a plugin object in which you can find a
-specific component class and instantiate it within a <<graph,trace
-processing graph>> as a <<comp,component>>.
+<<libbabeltrace2,libbabeltrace2>> can load a plugin (`.so`, `.dll`, or
+`.py` file) at run time: the result is a plugin object in which you can
+find a specific component class and instantiate it within a
+<<graph,trace processing graph>> as a <<comp,component>>.
+
-The <<babeltrace2-1,`babeltrace2` command>> uses the
-'TYPE.PLUGIN.COMPCLS' format to identify a specific component
-class within a specific plugin. 'TYPE' is either `source`, `filter`,
-or `sink`.
+The <<babeltrace2,`babeltrace2` program>> uses the
+'COMP-CLS-TYPE.PLUGIN-NAME.COMP-CLS-NAME' format to identify a specific
+component class within a specific plugin. 'COMP-CLS-TYPE' is either
+`source` (or `src`), `filter` (or `flt`), or `sink`.
+
-You can list the available Babeltrace plugins with the
+You can list the available Babeltrace~2 plugins with the
man:babeltrace2-list-plugins(1) command.
[[query]]Query::
An operation with which you can get a named object from a
- <<comp-cls,component class>>, possibly with the help of query
- parameters.
+ <<comp-cls,component class>>, possibly with custom query parameters.
+
The plain text metadata stream of a CTF trace and the available LTTng
-live sessions of a given LTTng relay daemon are examples of queries.
+live sessions of a given LTTng relay daemon are examples of query
+objects.
+
-You can use the man:babeltrace2-query(1) command to query a component
-class's object.
+You can use <<libbabeltrace2,libbabeltrace2>>, the
+<<python-bindings,Babeltrace~2 Python bindings>>, or the
+man:babeltrace2-query(1) CLI command to query a component class's
+object.
[[graph-repr]]
-TRACE PROCESSING GRAPH REPRESENTATION
--------------------------------------
-In the Babeltrace man pages, a component is represented with a box. The
-box has the <<comp-cls,component class>> type, <<plugin,plugin>> name,
-and component class name at the top. Just below, between square
-brackets, is its component instance name within the <<graph,trace
+== TRACE PROCESSING GRAPH REPRESENTATION
+
+In the Babeltrace~2 manual pages, a component is represented with a
+box. The box has the <<comp-cls,component class>> type,
+<<plugin,plugin>> name, and component class name at the top. Just below,
+between square brackets, is its component name within the <<graph,trace
processing graph>>. Each <<port,port>> is represented with an `@` symbol
-on the edge of the component box with its name inside the box. Output
-ports are on the right edge while input ports are on the left edge.
+on the border(s) of the component box with its name inside the box.
+Output ports are on the box's right border while input ports are on the
+box's left border.
For example, here's a source component box:
+------------+
----
-This one is an instance of the compcls:src.ctf.fs component class named
-`my-src`. It has three output ports named `stream0`, `stream1`, and
-`stream2`.
+This one is an instance of the compcls:source.ctf.fs component class
+named `my-src`. It has three output ports named `stream0`, `stream1`,
+and `stream2`.
A trace processing graph is represented with multiple component boxes
connected together. The <<conn,connections>> are arrows from output
+-----------------+
----
-Note that input port `in3` of component `muxer` is not currently
-connected in this example.
+Note that input port `in3` of component `muxer` is not connected in this
+example.
Sometimes, we symbolically represent other resources which are consumed
from or produced by components. In this case, arrows are used, but they
-do not go to or from port symbols (`@`). For example, in the graph above,
-the `ctf` component consumes a CTF trace and the `text` component
-prints to the console, so here's a more complete diagram:
+do not go to or from port symbols (`@`), except for messages. For
+example, in the graph above, the `ctf` source component consumes a CTF
+trace and the `text` sink component prints plain text to the terminal,
+so here's a more complete diagram:
----
- CTF trace
- |
-.------'
-| +------------+ +-----------------+ +------------------+
-| | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
-'->| [ctf] | | [muxer] | | [text] |
- | | | | | |
- | stream0 @--->@ in0 out @--->@ in |
- | stream1 @--->@ in1 | +--+---------------+
- | stream2 @--->@ in2 | |
- +------------+ @ in3 | '---> Console
- +-----------------+
+CTF trace
+ |
+ | +------------+ +-----------------+ +------------------+
+ | | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+ '-->| [ctf] | | [muxer] | | [text] |
+ | | | | | |
+ | stream0 @--->@ in0 out @--->@ in |
+ | stream1 @--->@ in1 | +-----+------------+
+ | stream2 @--->@ in2 | |
+ +------------+ @ in3 | '--> Terminal
+ +-----------------+
----
Here's another example of a more complex graph which splits a specific
include::common-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
man:babeltrace2(1)
-babeltrace2-list-plugins(1)
-==========================
+= babeltrace2-list-plugins(1)
:manpagetype: command
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-list-plugins - List Babeltrace plugins and their properties
+== NAME
+babeltrace2-list-plugins - List Babeltrace 2 plugins and their properties
+
+
+== SYNOPSIS
-SYNOPSIS
---------
[verse]
-*babeltrace2 list-plugins* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *list-plugins*
-DESCRIPTION
------------
-The `list-plugins` command prints a list of available Babeltrace
-plugins along with their component classes and their properties.
+== DESCRIPTION
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+The `list-plugins` command prints a list of available Babeltrace~2
+plugins along with their component classes and their properties.
+include::common-see-babeltrace2-intro.txt[]
-include::common-cmd-plugin-path.txt[]
+== OPTIONS
-OPTIONS
--------
include::common-gen-options.txt[]
-include::common-plugin-path-options.txt[]
-
include::common-cmd-info-options.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-help(1),
-man:babeltrace2-intro(7)
+man:babeltrace2-help(1)
-babeltrace2-plugin-ctf(7)
-========================
+= babeltrace2-plugin-ctf(7)
:manpagetype: plugin
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-plugin-ctf - Babeltrace's CTF plugin
+== NAME
+babeltrace2-plugin-ctf - Babeltrace 2's CTF plugin
-DESCRIPTION
------------
-The Babeltrace `ctf` plugin contains component classes which can read
-and write the http://diamon.org/ctf/[Common Trace Format].
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+== DESCRIPTION
+The Babeltrace~2 `ctf` plugin contains component classes to read
+and write traces following the https://diamon.org/ctf/[Common Trace
+Format].
-COMPONENT CLASSES
------------------
-compcls:sink.ctf.fs::
- Writes the received notifications as a CTF trace on the file system.
-+
-See man:babeltrace2-sink.ctf.fs(7).
+include::common-see-babeltrace2-intro.txt[]
+
+
+== COMPONENT CLASSES
compcls:source.ctf.fs::
- Opens one or more CTF traces on the file system and emits the
- notifications of their data stream files.
+ Opens a CTF trace on the file system and emits the messages of their
+ data stream files.
+
See man:babeltrace2-source.ctf.fs(7).
compcls:source.ctf.lttng-live::
- Connects to an http://lttng.org/[LTTng] relay daemon and emits
- the notifications of the received CTF data streams.
+ Connects to an https://lttng.org/[LTTng] relay daemon and emits
+ the messages of the received CTF data streams.
+
See man:babeltrace2-source.ctf.lttng-live(7).
+compcls:sink.ctf.fs::
+ Writes the consumed messages as one or more CTF traces on the file
+ system.
++
+See man:babeltrace2-sink.ctf.fs(7).
+
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-sink.ctf.fs(7),
+== SEE ALSO
+
+man:babeltrace2-intro(7),
man:babeltrace2-source.ctf.fs(7),
man:babeltrace2-source.ctf.lttng-live(7),
-man:babeltrace2-intro(7)
+man:babeltrace2-sink.ctf.fs(7)
-babeltrace2-plugin-lttng-utils(7)
-================================
+= babeltrace2-plugin-lttng-utils(7)
:manpagetype: plugin
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-plugin-lttng-utils - Babeltrace's LTTng utilities plugin
+== NAME
+babeltrace2-plugin-lttng-utils - Babeltrace 2's LTTng utilities plugin
-DESCRIPTION
------------
-The Babeltrace `lttng-utils` plugin contains utilities that apply to
-LTTng traces. You can use the compcls:source.ctf.fs and
+
+== DESCRIPTION
+
+The Babeltrace~2 `lttng-utils` plugin contains utilities that apply
+to LTTng traces. You can use the compcls:source.ctf.fs and
compcls:source.ctf.lttng-live components to read LTTng traces (see
man:babeltrace2-plugin-ctf(7)).
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+include::common-see-babeltrace2-intro.txt[]
-COMPONENT CLASSES
------------------
+== COMPONENT CLASSES
+
compcls:filter.lttng-utils.debug-info::
- Receives notifications from its input port and creates new,
- equivalent notifications with additionnal debugging information.
+ Adds debugging information to compatible LTTng event messages.
+
See man:babeltrace2-filter.lttng-utils.debug-info(7).
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-filter.lttng-utils.debug-info(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-filter.lttng-utils.debug-info(7)
-babeltrace2-plugin-text(7)
-=========================
+= babeltrace2-plugin-text(7)
:manpagetype: plugin
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-plugin-text - Babeltrace's plain text plugin
+== NAME
+babeltrace2-plugin-text - Babeltrace 2's plain text plugin
-DESCRIPTION
------------
-The Babeltrace `text` plugin contains component classes which read or
-write plain text data.
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+== DESCRIPTION
+The Babeltrace~2 `text` plugin contains component classes which
+read or write plain text data.
+
+include::common-see-babeltrace2-intro.txt[]
-COMPONENT CLASSES
------------------
-compcls:sink.text.pretty::
- Pretty-prints the notifications it receives to the console or to a
- file.
-+
-See man:babeltrace2-sink.text.pretty(7).
+
+== COMPONENT CLASSES
compcls:source.text.dmesg::
Reads the lines of a Linux kernel ring buffer, that is, the output
- of the man:dmesg(1) tool, and emits each line as an event
- notification.
+ of the man:dmesg(1) tool, and emits each line as an event message.
+
See man:babeltrace2-source.text.dmesg(7).
+compcls:sink.text.details::
+ Deterministically prints the messages it consumes with details to
+ the standard output.
++
+See man:babeltrace2-sink.text.details(7).
+
+compcls:sink.text.pretty::
+ Pretty-prints the messages it consumes to the standard output or to
+ a file.
++
+This is equivalent to the `text` output format of man:babeltrace(1)
+(Babeltrace~1).
++
+See man:babeltrace2-sink.text.pretty(7).
+
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-sink-text.text(7),
-man:babeltrace2-source-text.dmesg(7),
+== SEE ALSO
+
man:babeltrace2-intro(7),
+man:babeltrace2-source.text.dmesg(7),
+man:babeltrace2-sink.text.details(7),
+man:babeltrace2-sink.text.pretty(7)
-babeltrace2-plugin-utils(7)
-==========================
+= babeltrace2-plugin-utils(7)
:manpagetype: plugin
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-plugin-utils - Babeltrace's utilities plugin
+== NAME
+babeltrace2-plugin-utils - Babeltrace 2's common graph utilities plugin
-DESCRIPTION
------------
-The Babeltrace `utils` plugin contains common, generic utility component
-classes which you can use in any processing graph.
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+== DESCRIPTION
+The Babeltrace~2 `utils` plugin contains common, generic utility
+component classes which you can use in any processing graph.
+
+include::common-see-babeltrace2-intro.txt[]
+
+
+== COMPONENT CLASSES
-COMPONENT CLASSES
------------------
compcls:filter.utils.muxer::
- Multiplexes the notifications received on its multiple input ports
- by time to its single output port.
+ Muxes messages by time.
+
See man:babeltrace2-filter.utils.muxer(7).
compcls:filter.utils.trimmer::
- Discards all the received events with a timestamp less than a given
- beginning timestamp and greater than a given end timestamp,
- effectively ``cutting'' the traces.
+ Discards all the consumed messages with a time outside a given
+ time range, effectively ``cutting'' trace streams.
+
See man:babeltrace2-filter.utils.trimmer(7).
-compcls:sink.utils.dummy::
- Receives the notifications from its single input port and discards
- them (does absolutely nothing with them). This is useful for
- testing and benchmarking a trace processing graph application,
- for example man:babeltrace2(1).
-+
-See man:babeltrace2-sink.utils.dummy(7).
-
compcls:sink.utils.counter::
- Prints the number of notifications received from its single input
- port, either once at the end or periodically.
+ Prints the number of consumed messages, either once at the end or
+ periodically.
+
See man:babeltrace2-sink.utils.counter(7).
+compcls:sink.utils.dummy::
+ Consumes messages and discards them (does nothing with them).
++
+This is useful for testing and benchmarking a trace processing graph
+application, for example.
++
+See man:babeltrace2-sink.utils.dummy(7).
+
include::common-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
man:babeltrace2-intro(7),
man:babeltrace2-filter.utils.muxer(7),
man:babeltrace2-filter.utils.trimmer(7),
--- /dev/null
+= babeltrace2-query-babeltrace.support-info(7)
+:manpagetype: query object
+:revdate: 14 September 2019
+
+
+== NAME
+
+babeltrace2-query-babeltrace.support-info - Babeltrace 2's support info
+query object
+
+
+== DESCRIPTION
+
+The `babeltrace.support-info` Babeltrace~2 query object indicates,
+for a given source component class, whether or not its instance can
+handle a given input, and if so, what's the confidence of this support.
+
+Said input can be a simple string, an existing file path, or an existing
+directory path. Components which expect some form of URI can handle a
+string input, while components which expect an existing file or
+directory can handle a file/directory path input.
+
+When the source component class's query method replies that its
+component can handle a given input, it can also specify the name of a
+group in which to put that input. All the inputs of a given group, for a
+given component class, should be passed when instantiating the component
+class as its nlparam:inputs initialization parameter (array of strings).
+
+The man:babeltrace2-convert(1) command queries this object from specific
+source component classes to find the most appropriate for a given
+non-option argument.
+
+
+== PARAMETERS
+
+param:input='INPUT' vtype:[string]::
+ Check input 'INPUT'.
++
+Depending on the param:type parameter, this is a simple string, a file
+path, or a directory path.
+
+param:type=(`string` | `file` | `directory`) vtype:[string]::
+ Input type, one of:
++
+--
+`string`::
+ param:input parameter is a simple string.
+
+`file`::
+ param:input parameter is a file path.
+
+`directory`::
+ param:input parameter is a directory path.
++
+It is expected that the query method does not recurse into this
+directory: the result object indicates whether or not the component
+class supports this specific directory (param:input).
+--
+
+
+== RESULT OBJECT
+
+The result object can be one of:
+
+* [[simple-real]]A simple real value which is the weight, between 0 and
+ 1, of the support by the component class for the given input.
++
+A weight of 0 means the input is unsupported while a weight of 1 means
+it's fully supported. Any value in between shows how confident the
+component class is about the support of the given input.
+
+* A map with a weight and an optional group name.
+
+When it's a map, the expected entries are:
+
+qres:group='GROUP-NAME' vtype:[optional string]::
+ Put the given input into a group named 'GROUP-NAME' for this
+ component class.
++
+If this entry is missing, then the given input gets its own, unique
+group.
+
+qres:weight='WEIGHT' vtype:[real]::
+ Weight, between 0 and 1, of the support by the component class for
+ the given input.
++
+The semantics are the same as when the result object is a
+<<simple-real,simple real value>>.
+
+
+== EXAMPLES
+
+=== Query parameters
+
+.String input.
+====
+[source,yaml]
+----
+input: net://relayd177/host/node23/active
+type: string
+----
+====
+
+.File path input.
+====
+[source,yaml]
+----
+input: /home/user/traces/2019-08-26/quad.tr
+type: file
+----
+====
+
+=== Result object
+
+.Simple weight (unique group).
+====
+[source,yaml]
+----
+0.5
+----
+====
+
+.Weight and specific group.
+====
+[source,yaml]
+----
+group: 63a4b7e5-37f0-4254-a048-a0cff9e5b761
+weight: 0.75
+----
+====
+
+.Weight within a map (unique group).
+====
+[source,yaml]
+----
+weight: 0.6
+----
+====
+
+
+include::common-footer.txt[]
+
+
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-query(1),
+man:babeltrace2-convert(1)
--- /dev/null
+= babeltrace2-query-babeltrace.trace-infos(7)
+:manpagetype: query object
+:revdate: 14 September 2019
+
+
+== NAME
+
+babeltrace2-query-babeltrace.trace-infos - Babeltrace 2's trace infos
+query object
+
+
+== DESCRIPTION
+
+The `babeltrace.trace-infos` Babeltrace~2 query object indicates
+time range information about specific traces and their streams, and
+which output ports of an eventual source component will serve the
+messages for a given stream.
+
+The man:babeltrace2-convert(1) command queries this object from all the
+source component classes to support the
+manopt:babeltrace2-convert(1):--stream-intersection feature.
+
+
+== PARAMETERS
+
+The parameters for this query operation are exactly the same as you
+would pass as the initialization parameters of a component created from
+the queried component class.
+
+
+== RESULT OBJECT
+
+The result object is an array of trace info maps (see
+<<trace-info-map,``Trace info map''>>).
+
+
+[[trace-info-map]]
+=== Trace info map
+
+A trace info map contains:
+
+nlqres:stream-infos='STREAM-INFOS' vtype:[array of stream info maps]::
+ Stream info maps (see <<stream-info-map,``Stream info map''>>) for
+ this trace.
+
+
+[[stream-info-map]]
+=== Stream info map
+
+A stream info map contains:
+
+nlqres:range-ns='RANGE' vtype:[range map]::
+ The time range of this stream, a map containing:
++
+--
+nlqres:begin='NS' vtype:[signed integer]::
+ Beginning time of this stream (nanoseconds since the stream
+ class's default clock class's origin).
+
+nlqres:end='NS' vtype:[signed integer]::
+ End time of this stream (nanoseconds since the stream class's
+ default clock class's origin).
+--
+
+nlqres:port-name='PORT-NAME' vtype:[string]::
+ For an eventual source component initialized with the same
+ parameters: name of the output port which serves the messages of
+ this stream.
+
+
+== EXAMPLES
+
+=== Result object
+
+.Two trace infos: one with three stream infos, one with two stream infos.
+====
+[source,yaml]
+----
+- stream-infos:
+ - range-ns:
+ begin: 1509556764975082000
+ end: 1509557102181554400
+ port-name: trace0-cpu0
+ - range-ns:
+ begin: 1509556764947050800
+ end: 1509557102182771000
+ port-name: trace0-cpu1
+ - range-ns:
+ begin: 1509556764956409300
+ end: 1509557102182770400
+ port-name: trace0-cpu2
+- stream-infos:
+ - range-ns:
+ begin: 1509556764918082000
+ end: 1509557103849928400
+ port-name: trace1-cpu0
+ - range-ns:
+ begin: 1509556761888820000
+ end: 1509557109928100400
+ port-name: trace1-cpu1
+
+----
+====
+
+
+include::common-footer.txt[]
+
+
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-query(1),
+man:babeltrace2-convert(1)
-babeltrace2-query(1)
-===================
+= babeltrace2-query(1)
:manpagetype: command
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-query - Query object from a component class
+== NAME
+
+babeltrace2-query - Query an object from a Babeltrace 2 component class
-SYNOPSIS
---------
+== SYNOPSIS
+
[verse]
-*babeltrace2 query* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- [opt:--params='PARAMS'] 'TYPE.PLUGIN.COMPCLS' 'OBJECT'
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *query* [opt:--params='PARAMS']
+ 'COMP-CLS-TYPE'.'PLUGIN-NAME'.'COMP-CLS-NAME' 'OBJECT'
+
+== DESCRIPTION
-DESCRIPTION
------------
The `query` command queries the object named 'OBJECT' from the component
-class 'COMPCLS' of the type 'TYPE' found in the Babeltrace plugin
-'PLUGIN' and prints the results.
+class named 'COMP-CLS-NAME' of the type 'COMP-CLS-TYPE' found in the
+Babeltrace~2 plugin named 'PLUGIN-NAME' and prints the results.
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+include::common-see-babeltrace2-intro.txt[]
-The available values for 'TYPE' are:
+The available values for 'COMP-CLS-TYPE' are:
`source`::
`src`::
Sink component class.
The exact object names and the parameters that a given component class
-expects are described in its documentation. man:babeltrace2-help(1) can
-generally provide this information.
+expects are described in its own documentation. man:babeltrace2-help(1)
+can generally provide this information.
-You can use the opt:--params='PARAMS' option to pass parameters to the
-component class's query function. See <<params-fmt,Parameters format>>
-for the exact format of 'PARAMS'.
+You can use the opt:--params option to pass parameters to the component
+class's query operation.
-The output of the `query` command looks like YAML, although it is not
-guaranteed that it is YAML-compliant.
+The output of the `query` command can look like https://yaml.org/[YAML],
+but it's not guaranteed to be YAML-compliant.
-See <<examples,EXAMPLES>> for usage examples.
-
-
-include::common-cmd-params-format.txt[]
+See <<examples,``EXAMPLES''>> for usage examples.
-include::common-cmd-plugin-path.txt[]
+== OPTIONS
-OPTIONS
--------
include::common-gen-options.txt[]
-Query parameters
-~~~~~~~~~~~~~~~~
-opt:-p 'PARAMS', opt:--params='PARAMS'::
- Set the query parameters to 'PARAMS'. See <<params-fmt,Parameters
- format>> for the exact format of 'PARAMS'.
+=== Query parameters
+opt:-p 'PARAMS'::
+opt:--params='PARAMS'::
+ Set the query parameters to 'PARAMS'.
++
+--
+include::common-cmd-params-format.txt[]
+--
-include::common-plugin-path-options.txt[]
include::common-cmd-info-options.txt[]
[[examples]]
-EXAMPLES
---------
-.Query the available sessions of the LTTng live source component class.
+== EXAMPLES
+
+.Query the available tracing sessions of a local LTTng relay daemon.
====
[role="term"]
----
$ babeltrace2 query src.ctf.lttng-live sessions \
- --params='url="net://RHOST/host/TGTHOST"'
+ --params='url="net://localhost"'
----
====
-.Query the metadata info (includes the decoded text) of a CTF trace located on the local file system.
+.Query the metadata info (includes the decoded plain text) of a CTF trace located on the local file system.
====
[role="term"]
----
$ babeltrace2 query src.ctf.fs metadata-info \
- --params='path="/path/to/trace"'
+ --params='path="/path/to/trace"'
----
====
-.Query the trace info of CTF traces located on the local file system.
+.Query the trace infos of a CTF trace located on the local file system.
====
[role="term"]
----
-$ babeltrace2 query src.ctf.fs babeltrace.trace-info \
+$ babeltrace2 query src.ctf.fs babeltrace.trace-infos \
--params='path="/path/to/trace"'
----
====
include::common-cli-env.txt[]
+
include::common-cli-files.txt[]
+
include::common-cmd-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2(1),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2(1)
-babeltrace2-run(1)
-=================
+= babeltrace2-run(1)
:manpagetype: command
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-run - Create a trace processing graph and run it
+== NAME
+
+babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it
-SYNOPSIS
---------
+[[synopsis]]
+== SYNOPSIS
+
[verse]
-*babeltrace2 run* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- [opt:--retry-duration='DURUS']
- opt:--connect='CONN-RULE'... 'COMPONENTS'
+*babeltrace2* [<<gen-opts,'GENERAL OPTIONS'>>] *run* [opt:--retry-duration='TIME-US']
+ opt:--connect='CONN-RULE'... 'COMPONENTS'
+
+== DESCRIPTION
-DESCRIPTION
------------
-The `run` command creates a trace processing graph and runs it.
+The `run` command creates a Babeltrace~2 trace processing graph and
+runs it.
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+include::common-see-babeltrace2-intro.txt[]
-The `run` command uses libbabeltrace2 to dynamically load plugins which
+The `run` command dynamically loads Babeltrace~2 plugins which
supply component classes. With the `run` command, you specify which
-component classes to instantiate as components and how they must be
-connected.
+component classes to instantiate as components and how to connect them.
The steps to write a `babeltrace2 run` command line are:
-. Specify which component classes to instantiate as components and
- how. This is the 'COMPONENTS' part of the synopsis. See
- <<create-comps,Create components>> to learn more.
+. Specify which component classes to instantiate as components with many
+ opt:--component options and how to configure them.
++
+This is the 'COMPONENTS' part of the <<synopsis,synopsis>>. See
+<<create-comps,``Create components''>> to learn more.
-. Specify how to connect component instances together with one or more
- opt:--connect options. See <<connect-comps,Connect components>> to
- learn more.
+. Specify how to connect components together with one or more
+ opt:--connect options.
++
+See <<connect-comps,``Connect components''>> to learn more.
NOTE: The man:babeltrace2-convert(1) command is a specialization of the
`run` command for the very common case of converting one or more traces:
[[create-comps]]
-Create components
-~~~~~~~~~~~~~~~~~
+=== Create components
+
To create a component, use the opt:--component option. This option
specifies:
-* **Optional**: The name of the component instance. You can also use the
- opt:--name option for this.
+* The name of the component, unique amongst all the component names of
+ the trace processing graph.
* The type of the component class to instantiate: source, filter, or
sink.
* The name of the component class to instantiate.
-You can use the opt:--component option multiple times to create
-multiple components. You can instantiate the same component class
-multiple times as different component instances.
+Use the opt:--component option multiple times to create multiple
+components. You can instantiate the same component class multiple times
+as different components.
At any point in the command line, the opt:--base-params sets the current
base initialization parameters and the opt:--reset-base-params resets
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'.
+The opt:--params='PARAMS' option adds parameters to the current
+component's initialization parameters. If 'PARAMS' contains a key which
+exists in the current component's initialization parameters, this
+parameter is replaced.
[[connect-comps]]
-Connect components
-~~~~~~~~~~~~~~~~~~
+=== Connect components
+
The components which you create from component classes with the
-opt:--component option (see <<create-comps,Create components>>) can
-create input and output _ports_ depending on their type. An output port
-is where notifications, like trace events, are sent. An input port is
-where notifications are received. For a given component instance, each
-port has a unique name.
+opt:--component option (see <<create-comps,``Create components''>>) add
+input and output _ports_ depending on their type. An output port is from
+where messages, like trace events, are sent. An input port is where
+messages are received. For a given component, each port has a unique
+name.
The purpose of the `run` command is to create a trace processing graph,
that is, to know which component ports to connect together. The command
achieves this with the help of the connection rules that you provide
-with the opt:--connect option.
+with one or more opt:--connect='CONN-RULE' options.
-The format of a connection rule (the argument of the opt:--connect
-option) is:
+The format of 'CONN-RULE' is:
[verse]
__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
-'UP-COMP-PATH'::
+'UP-COMP-PAT'::
Upstream component name pattern.
'UP-PORT-PAT'::
- Upstream port name pattern.
+ Upstream (output) port name pattern.
-'DOWN-COMP-PATH'::
+'DOWN-COMP-PAT'::
Downstream component name pattern.
'DOWN-PORT-PAT'::
- Downstream port name pattern.
+ Downstream (input) port name pattern.
When a source or filter component adds a new output port within the
processing graph, the `run` command does the following to find an
input port to connect it to:
----
-For each connection rule:
- If the output port's component's name matches UP-COMP-PAT and
- the output port's name matches UP-PORT-PAT:
- For each component COMP in the processing graph:
+For each connection rule (--connect options, in order):
+ If the output port's component's name matches UP-COMP-PAT and the
+ output port's name matches UP-PORT-PAT:
+ For each component COMP in the trace processing graph:
If the name of COMP matches DOWN-COMP-PAT:
- Select the first input port of COMP of which the name
- matches DOWN-PORT-PAT, or fail with no match.
-Fail with no match.
+ Select the first input port of COMP of which the name matches
+ DOWN-PORT-PAT, or fail with no match.
+
+No possible connection: fail with no match.
----
__UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
equivalent to `*`.
You can leverage this connection mechanism to specify fallbacks with a
-careful use of wildcards. For example:
+careful use of wildcards, as the order of the opt:--connect options on
+the command line is significant. For example:
----
--connect='A.out*:B.in*' --connect=A:B --connect='*:C'
----
-With those connection rules:
+With those connection rules, the `run` command connects:
* Any output port of which the name starts with `out` of component `A`
- is connected to the first input port of which the name starts with
- `in` of component `B`.
+ to the first input port of which the name starts with `in` of
+ component `B`.
-* Any other output port of component `A` is connected to the first
- available input port of component `B`.
+* Any other output port of component `A` to the first available input
+ port of component `B`.
-* Any other output port (of any component except `A`) is connected to
- the first available input port of component `C`.
+* Any other output port (of any component except `A`) to the first
+ available input port of component `C`.
The `run` command fails when it cannot find an input port to which to
-connect a created output port using the provided connection
-rules.
+connect a given output port using the provided connection rules.
-See <<examples,EXAMPLES>> for more examples.
+See <<examples,``EXAMPLES''>> for more examples.
-include::common-cmd-params-format.txt[]
+== OPTIONS
-include::common-cmd-plugin-path.txt[]
+include::common-gen-options.txt[]
-OPTIONS
--------
-include::common-gen-options.txt[]
+=== Component creation
+See <<create-comps,``Create components''>> for more details.
-Component creation
-~~~~~~~~~~~~~~~~~~
-opt:-b 'PARAMS', opt:--base-params='PARAMS'::
- Set the current base parameters to 'PARAMS'. You can reset the
- current base parameters with the opt:--reset-base-params option.
- See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+opt:-b 'PARAMS'::
+opt:--base-params='PARAMS'::
+ Set the current base parameters to 'PARAMS'.
++
+You can reset the current base parameters with the
+opt:--reset-base-params option.
++
+See the opt:--params option for the format of 'PARAMS'.
-opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
- Create a component initially named 'NAME' (if specified) from the
- component class of type 'TYPE' named 'COMPCLS' found in the plugin
- named 'PLUGIN', and set it as the current component.
+opt:-c __NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME'::
+opt:--component=__NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME'::
+ Create a component named 'NAME' from the component class of type
+ 'COMP-CLS-TYPE' named 'COMP-CLS-NAME' found in the plugin named
+ 'PLUGIN-NAME', and set it as the current component.
+
The available values for 'TYPE' are:
+
the current base initialization parameters (see the opt:--base-params
option).
-opt:--name='NAME'::
- Set the name of the current component to 'NAME'. The names of all
- the components in the processing graph must be unique.
+opt:-l 'LVL'::
+opt:--log-level='LVL'::
+ Set the log level of the current component to 'LVL'.
++
+The available values for 'LVL' are:
++
+--
+include::common-log-levels.txt[]
+--
-opt:-p 'PARAMS', opt:--params='PARAMS'::
+opt:-p 'PARAMS'::
+opt:--params='PARAMS'::
Add 'PARAMS' to the initialization parameters of the current
- component. If 'PARAMS' contains a key which exists in the current
- component's initialization parameters, replace the parameter.
- See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+ component.
++
+If 'PARAMS' contains a key which exists in the current component's
+initialization parameters, replace the parameter.
++
+--
+include::common-cmd-params-format.txt[]
+--
+
+opt:-r::
+opt:--reset-base-params::
+ Reset the current base parameters.
++
+You can set the current base parameters with the opt:--base-params
+option.
+
-opt:-r, opt:--reset-base-params::
- Reset the current base parameters. You can set the current base
- parameters with the opt:--base-params option.
+=== Component connection
+opt:-x 'CONN-RULE'::
+opt:--connect='CONN-RULE'::
+ Add the connection rule 'CONN-RULE'.
++
+The format of 'CONN-RULE' is:
++
+[verse]
+__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
++
+--
+'UP-COMP-PAT'::
+ Upstream component name pattern.
+
+'UP-PORT-PAT'::
+ Upstream (output) port name pattern.
+
+'DOWN-COMP-PAT'::
+ Downstream component name pattern.
+
+'DOWN-PORT-PAT'::
+ Downstream (input) port name pattern.
+--
++
+See <<connect-comps,``Connect components''>> to learn more.
-Component connection
-~~~~~~~~~~~~~~~~~~~~
-opt:-x 'CONN-RULE', opt:--connect='CONN-RULE'::
- Add the connection rule 'CONN-RULE'. See
- <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
+=== Graph configuration
-Graph configuration
-~~~~~~~~~~~~~~~~~~~
-opt:--retry-duration='DURUS'::
- Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+opt:--retry-duration='TIME-US'::
+ Set the duration of a single retry to 'TIME-US'~µs when a sink
component reports "try again later" (busy network or file system,
for example).
+
-Default: 100000 (100{nbsp}ms).
+Default: 100000 (100~ms).
-include::common-plugin-path-options.txt[]
-
include::common-cmd-info-options.txt[]
[[examples]]
-EXAMPLES
---------
+== EXAMPLES
+
.Create a single-port source component and a single-port sink component and connect them.
====
[role="term"]
----
$ babeltrace2 run --component=A:src.plug.my-src \
- --component=B:sink.plug.my-sink \
- --connect=A:B
+ --component=B:sink.plug.my-sink \
+ --connect=A:B
----
Possible resulting graph:
----
====
-.Use the opt:--name option to name the current component.
-====
-[role="term"]
-----
-$ babeltrace2 run --component=src.plug.my-src --name=the-source \
- --component=the-sink:sink.plug.my-sink \
- --connect=the-source:the-sink
-----
-====
-
.Use the opt:--params option to set the current component's initialization parameters.
====
In this example, the opt:--params option only applies to component
[role="term"]
----
$ babeltrace2 run --component=the-source:src.my-plugin.my-src \
- --params='offset=123, flag=true' \
- --component=the-sink:sink.my-plugin.my-sink \
- --connect=the-source:the-sink
+ --params=offset=123,flag=true \
+ --component=the-sink:sink.my-plugin.my-sink \
+ --connect=the-source:the-sink
----
====
In this example, the effective initialization parameters of the
created components are:
-* Component `A`: `offset=1203, flag=false`
-* Component `B`: `offset=1203, flag=true, type=event`
-* Component `C`: `ratio=0.25`
+Component `A`::
+ `offset=1203, flag=false`
+
+Component `B`::
+ `offset=1203, flag=true, type=event`
+
+Component `C`::
+ `ratio=0.25`
[role="term"]
----
-$ babeltrace2 run --base-params='offset=1203, flag=false' \
- --component=A:src.plugin.compcls \
- --component=B:flt.plugin.compcls \
- --params='flag=true, type=event' \
- --reset-base-params \
- --component=C:sink.plugin.compcls \
- --params='ratio=0.25' \
- --connect=A:B --connect=B:C
+$ babeltrace2 run --base-params=offset=1203,flag=false \
+ --component=A:src.plugin.compcls \
+ --component=B:flt.plugin.compcls \
+ --params=flag=true,type=event \
+ --reset-base-params \
+ --component=C:sink.plugin.compcls \
+ --params=ratio=0.25 \
+ --connect=A:B --connect=B:C
----
====
[role="term"]
----
$ babeltrace2 run --component=A:src.plug.my-src \
- --component=B:sink.plug.my-sink \
- --connect='A.foo*:B:nin*' --connect='A:B.oth*'
+ --component=B:sink.plug.my-sink \
+ --connect='A.foo*:B:nin*' --connect='A:B.oth*'
----
Possible resulting graph:
include::common-cli-env.txt[]
+
include::common-cli-files.txt[]
+
include::common-cmd-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
+man:babeltrace2-intro(7),
man:babeltrace2(1),
-man:babeltrace2-convert(1),
-man:babeltrace2-intro(7)
+man:babeltrace2-convert(1)
-babeltrace2-sink.ctf.fs(7)
-=========================
+= babeltrace2-sink.ctf.fs(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-sink.ctf.fs - Babeltrace's file system CTF sink component
+== NAME
+
+babeltrace2-sink.ctf.fs - Babeltrace 2's file system CTF sink component
class
-DESCRIPTION
------------
-The Babeltrace compcls:sink.ctf.fs component class, provided by the
-man:babeltrace2-plugin-ctf(7) plugin, once instantiated, writes the
-events it receives to one or more http://diamon.org/ctf/[CTF] traces on
+== DESCRIPTION
+
+A Babeltrace~2 compcls:sink.ctf.fs component writes the messages it
+consumes to one or more https://diamon.org/ctf/[CTF]~1.8 traces on
the file system.
-A compcls:sink.ctf.fs component does not merge traces, in that it writes
-the notifications of different input traces to different output traces.
+----
+ +-------------+
+ | sink.ctf.fs |
+ | +--> CTF trace(s) on
+Messages -->@ in | the file system
+ +-------------+
+----
+
+include::common-see-babeltrace2-intro.txt[]
+
+A compcls:sink.ctf.fs component does not merge traces: it writes the
+messages of different input traces to different output traces.
+
+
+=== Special trace IR to CTF translations
+
+A compcls:sink.ctf.fs component makes a best effort to write CTF traces
+that are semantically equivalent to the input traces. As of this
+version, the component writes CTF~1.8 traces, so the following
+field class translations can occur:
+
+* The component translates a boolean field class to a CTF unsigned 8-bit
+ integer field class.
++
+The unsigned integer field's value is 0 when the boolean field's value
+is false and 1 when the boolean field's value is true.
+
+* The component translates a bit array field to a CTF unsigned
+ integer field class having the same length.
+
+* The component translates an option field class to a CTF variant
+ field class where the options are an empty structure field class
+ and the optional field class itself.
++
+The empty structure field is selected when the option field has no
+field.
+
+In all the cases above, the component adds a comment in the metadata
+stream, above the field class, to indicate that a special translation
+occured.
+
+
+=== Input message constraints
+
+Because of limitations in CTF~1.8 regarding how discarded events
+and packets are encoded:
+
+* If a stream class supports discarded events and the
+ param:ignore-discarded-events parameter is :not: true:
+
+** The stream class must support packets.
+** Discarded events messages must have times.
+** Any discarded events message must occur between a packet end
+ and a packet beginning message.
+** The beginning time of a discarded events message must be the same
+ as the time of the last packet end message.
+** The end time of a discarded events message must be the same
+ as the time of the next packet end message.
+** Time ranges of discarded events messages must not overlap.
+
+* If a stream class supports discarded packets and the
+ param:ignore-discarded-packets parameter is :not: true:
+
+** The stream class must support packets.
+** Discarded packets messages must have times.
+** The beginning time of a discarded events message must be the same
+ as the time of the last packet end message.
+** The end time of a discarded events message must be the same
+ as the time of the next packet beginning message.
+** Time ranges of discarded packets messages must not overlap.
-This component guarantees that the output traces are semantically
-equivalent to the input traces. This means that a given output CTF trace
-contains:
+The messages which a compcls:source.ctf.fs component creates satisfy all
+the requirements above.
-* The original trace environment.
-* The original clock classes.
-* The original event class names, log levels, and other static
- attributes, except for the numeric IDs.
-* The original field _values_, except for:
-** Timestamp fields, but the equivalent clock value remains the same.
-** Numeric ID fields.
+If a discarded events or packets message has no events/packets count,
+the compcls:sink.ctf.fs component adds 1 to the corresponding CTF
+stream's counter.
-The component does not guarantee to keep:
-* The original field type attributes (for example, the sizes of the
- integer field types).
-* The original stream class and event class numeric IDs.
+=== Alignment and byte order
+A compcls:sink.ctf.fs component always aligns data fields as such:
+
+Integer fields with a size which is not a multiple of 8::
+ 1-bit.
+
+All other scalar fields (integer, enumeration, real, string)::
+ 8-bit.
+
+The component writes fields using the machine's native byte order. As of
+this version, there's no way to force a custom byte order.
+
+
+[[output-path]]
+=== Output path
-Output path
-~~~~~~~~~~~
The path of a CTF trace is the directory which directly contains the
-metadata and data stream files as children.
+metadata and data stream files.
-The rules to determine the path of a generated CTF trace are:
+The current strategy to build a path in which to write the streams of
+a given input trace is, in this order:
-* If the param:single-trace parameter is true, use the value of the
- param:path parameter.
+. If the param:assume-single-trace parameter is true, then the output
+ trace path to use for the single input trace is the directory
+ specified by the param:path parameter.
+
+. If the component recognizes the input trace as an LTTng (2.11 or
+ greater) trace, then it checks specific trace environment values to
+ build a trace path relative to the directory specified by the
+ param:path parameter:
+
-Otherwise:
+--
+
+Linux kernel domain::
++
+[verse]
+__HOST__/__SNAME__-__STIME__/kernel
+
+User space domain, per-UID buffering::
+
+[verse]
+__HOST__/__SNAME__-__STIME__/ust/uid/__UID__/__ARCHW__-bit
+
+User space domain, per-PID buffering::
++
+[verse]
+__HOST__/__SNAME__-__STIME__/ust/pid/__PNAME__-__PID__-__PTIME__
+
--
-* If the input trace has a name, use `OUTPUTPATH/TRACENAME[SUFFIX]`,
- where `OUTPUTPATH` is the value of the param:path parameter,
- `TRACENAME` is the input trace's name, and `SUFFIX` is an optional
- numeric suffix if `OUTPUTPATH/TRACENAME` already exists.
+
-Note that the name of a trace that a compcls:source.ctf.fs component
-creates includes its hostname and its relative path while making sure to
-avoid conflicts.
+With:
+
-Otherwise, use `OUTPUTPATH/trace[SUFFIX]`, where `OUTPUTPATH` and
-`SUFFIX` are defined above.
--
+__HOST__::
+ Target's hostname.
+__SNAME__::
+ Tracing session name.
-INITIALIZATION PARAMETERS
--------------------------
-param:path='PATH' (string, mandatory)::
- Depending on the value of the param:single-trace parameter, prefix
- of output trace paths or full output trace path.
+__STIME__::
+ Tracing session creation date/time.
-param:single-trace=`yes` (boolean, optional)::
- Assume that the component only receives notifications related to
- a single source trace.
+__UID__::
+ User ID.
+__ARCHW__::
+ Architecture's width (`32` or `64`).
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications.
+__PNAME__::
+ Process name.
+__PID__::
+ Process ID.
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+__PTIME__::
+ Process's date/time.
+--
+. If the input trace has a name, then the component sanitizes this name
+ and uses it as a relative path to the directory specified by the
+ param:path parameter.
++
+The trace name sanitization operation:
++
+* Replaces `.` subdirectories with `_`.
+* Replaces `..` subdirectories with `__`.
+* Removes any trailing `/` character.
-ENVIRONMENT VARIABLES
----------------------
-include::common-ctf-plugin-env.txt[]
+. The component uses the subdirectory `trace` relative to the directory
+ specified by the param:path parameter.
+In all the cases above, if the effective output trace path already
+exists on the file system, the component appends a numeric suffix to the
+name of the last subdirectory. The suffix starts at 0 and increments
+until the path does not exist.
-Component class
-~~~~~~~~~~~~~~~
-include::common-common-compat-env.txt[]
-`BABELTRACE_SINK_CTF_FS_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
+== INITIALIZATION PARAMETERS
+
+param:assume-single-trace=`yes` vtype:[optional boolean]::
+ Assume that the component only receives messages related to a single
+ input trace.
++
+This parameter affects how the component builds the output trace path
+(see <<output-path,``Output path''>>).
+
+param:ignore-discarded-events=`yes` vtype:[optional boolean]::
+ Ignore discarded events messages.
+
+param:ignore-discarded-packets=`yes` vtype:[optional boolean]::
+ Ignore discarded packets messages.
+
+param:path='PATH' vtype:[string]::
+ Base output path.
++
+See <<output-path,``Output path''>> to learn how the component uses this
+parameter to build the output path for a given input trace.
+
+param:quiet=`yes` vtype:[optional boolean]::
+ Do not write anything to the standard output.
+
+
+== PORTS
+
+----
++-------------+
+| sink.ctf.fs |
+| |
+@ in |
++-------------+
+----
+
+
+=== Input
+
+`in`::
+ Single input port.
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-ctf(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-ctf(7)
--- /dev/null
+= babeltrace2-sink.text.details(7)
+:manpagetype: component class
+:revdate: 14 September 2019
+
+
+== NAME
+
+babeltrace2-sink.text.details - Babeltrace 2's detailed plain text sink
+component class
+
+
+== DESCRIPTION
+
+A Babeltrace~2 compcls:sink.text.details component
+deterministically prints the messages it consumes, with all the possible
+details, to the standard output.
+
+----
+ +-------------------+
+ | sink.text.details |
+ | +--> Detailed messages to the
+Messages -->@ in | standard output
+ +-------------------+
+----
+
+include::common-see-babeltrace2-intro.txt[]
+
+The purpose of a compcls:sink.text.details component is to always print
+the same text for the same sequence of consumed messages, whatever the
+build configuration of the Babeltrace~2 project. This can be
+helpful for testing, debugging, and support.
+
+The output format is optimized for human reading, with colors when the
+terminal supports it. You can control how the component prints color
+codes with the param:color parameter.
+
+To achieve a reproducible output, a compcls:sink.text.details component
+sorts the members of all unordered sets before it prints them. For
+example, the component sorts enumeration field class mappings by label
+and, for each mapping, sorts the contained ranges.
+
+In normal mode, each message has at least three lines, the three first
+being:
+
+. Timing information (cycles and nanoseconds since origin).
++
+Example:
++
+----
+[102,423,274,041,829 cycles, 1,441,852,841,550,867,846 ns from origin]
+----
+
+. Unique stream identifier.
++
+To be able to follow a specific trace object (the name and UUID
+properties of a trace object are optional), the component assigns a
+unique numeric ID to the trace object when it first encounters it in a
+stream beginning message.
++
+Example:
++
+----
+{Trace 1, Stream class ID 0, Stream ID 2}
+----
+
+. Message type and basic information.
++
+Examples:
++
+----
+Packet beginning:
+----
++
+----
+Event `lttng_ust_statedump:build_id` (Class ID 2):
+----
+
+What follows depend on the specific message type. The component prints
+all the available properties and fields in a human-readable, structured
+format.
+
+When a compcls:sink.text.details component consumes a stream beginning
+or an event message, it can print a metadata block for all the metadata
+objects which it did not print yet. You can use the param:with-metadata
+parameter to disable this.
+
+You can hide specific properties with the param:with-stream-class-name,
+param:with-stream-name, param:with-time, param:with-trace-name, and
+param:with-uuid parameters.
+
+To make the component hide many message details and print a single
+message per line, you can enable the compact mode with the param:compact
+parameter.
+
+
+== INITIALIZATION PARAMETERS
+
+param:color=(`never` | `auto` | `always`) vtype:[optional string]::
+ Force the terminal color support, one of:
++
+--
+`auto` (default)::
+ 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.
+
+`always`::
+ Always emit terminal color codes.
+--
++
+The `BABELTRACE_TERM_COLOR` environment variable overrides this
+parameter.
+
+param:compact=`yes` vtype:[optional boolean]::
+ Enable compact mode.
++
+In compact mode, the component prints one line per message, omitting
+many details about messages. This is useful if you only need the time,
+type, and very basic information of messages.
++
+In compact mode, the component still prints the full metadata blocks.
+You can remove such blocks with the param:with-metadata parameter.
+
+param:with-metadata=`no` vtype:[optional boolean]::
+ Do not print metadata blocks.
+
+param:with-stream-class-name=`no` vtype:[optional boolean]::
+ Do not print stream class names.
+
+param:with-stream-name=`no` vtype:[optional boolean]::
+ Do not print stream names.
+
+param:with-time=`no` vtype:[optional boolean]::
+ Do not print timing information.
+
+param:with-trace-name=`no` vtype:[optional boolean]::
+ Do not print trace names.
+
+param:with-uuid=`no` vtype:[optional boolean]::
+ Do not print UUIDs.
+
+
+== PORTS
+
+----
++-------------------+
+| sink.text.details |
+| |
+@ in |
++-------------------+
+----
+
+
+=== Input
+
+`in`::
+ Single input port.
+
+
+== ENVIRONMENT VARIABLES
+
+include::common-common-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-text(7)
-babeltrace2-sink.text.pretty(7)
-==============================
+= babeltrace2-sink.text.pretty(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-sink.text.pretty - Babeltrace's pretty-printing sink
+== NAME
+
+babeltrace2-sink.text.pretty - Babeltrace 2's pretty-printing sink
component class
-DESCRIPTION
------------
-The Babeltrace compcls:sink.text.pretty component class, provided by the
-man:babeltrace2-plugin-text(7) plugin, once instantiated, pretty-prints
-the events it receives from its input port to the console or to a file.
+== DESCRIPTION
+
+A Babeltrace~2 compcls:sink.text.pretty component pretty-prints the
+events, discarded events, and discarded packets messages it consumes to
+the standard output or to a file.
+
+----
+ +------------------+
+ | sink.text.pretty |
+ | +--> Pretty-printed messages to
+Messages -->@ in | the standard output or a file and
+ +------------------+ to the standard error
+----
+
+include::common-see-babeltrace2-intro.txt[]
+
+By default, a compcls:sink.text.pretty component pretty-prints to the
+standard output. You can use the param:path parameter to make the
+component write to a file instead.
-By default, a compcls:sink.text.pretty component pretty-prints to
-the standard output. You can use the param:path parameter for the
-component to write to a file instead.
+The component prints warnings on the standard error stream when it
+consumes a discarded events or discarded packets message.
-The component also prints warnings on the standard error stream when it
-receives a discarded packets or discarded events notification.
+If you don't use the param:path parameter and the application's standard
+output is connected to a color-capable terminal, the component emits
+terminal color codes to enhance the text output. You can use the
+param:color parameter to force the color support or to disable it.
-If you don't use the param:path parameter and the application's
-standard output is connected to a color-capable terminal, the component
-emits terminal color codes to enhance the text output for human
-consumption. You can use the param:color parameter to force the color
-support or to disable it.
+This component class is equivalent to the `text` output format of
+man:babeltrace(1) (Babeltrace~1 command-line tool).
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
+== INITIALIZATION PARAMETERS
-param:clock-cycles=`yes` (boolean)::
+param:clock-cycles=`yes` vtype:[optional boolean]::
Print event times in clock cycles instead of hours, minutes,
seconds, and nanoseconds.
-param:clock-date=`yes` (boolean)::
+param:clock-date=`yes` vtype:[optional boolean]::
Print event times _and_ dates.
-param:clock-gmt=`yes` (boolean)::
+param:clock-gmt=`yes` vtype:[optional boolean]::
Print event times in the GMT time zone instead of the local time
zone.
-param:clock-seconds=`yes` (boolean)::
+param:clock-seconds=`yes` vtype:[optional boolean]::
Print event times in seconds instead of hours, minutes,
seconds, and nanoseconds.
-param:color=(`never` | `auto` | `always`) (string)::
+param:color=(`never` | `auto` | `always`) vtype:[optional string]::
Force the terminal color support, one of:
+
--
The `BABELTRACE_TERM_COLOR` environment variable overrides this
parameter.
-param:field-default=(`show` | `hide`) (string)::
+param:field-default=(`show` | `hide`) vtype:[optional string]::
By default, show or hide all the fields. This sets the default value
of all the parameters which start with `field-`.
-param:field-emf=(`yes` | `no`) (boolean)::
+param:field-emf=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the event's Eclipse Modeling Framework URI field.
-param:field-loglevel=(`yes` | `no`) (boolean)::
+param:field-loglevel=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the event's logging level field.
-param:field-trace=(`yes` | `no`) (boolean)::
+param:field-trace=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the trace name field.
-param:field-trace:domain=(`yes` | `no`) (boolean)::
+param:field-trace:domain=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the tracing domain field.
-param:field-trace:hostname=(`yes` | `no`) (boolean)::
+param:field-trace:hostname=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the hostname field.
-param:field-trace:procname=(`yes` | `no`) (boolean)::
+param:field-trace:procname=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the process name field.
-param:field-trace:vpid=(`yes` | `no`) (boolean)::
+param:field-trace:vpid=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the virtual process ID field.
-param:name-context=(`yes` | `no`) (boolean)::
+param:name-context=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the field names in the context scopes.
-param:name-default=(`show` | `hide`) (string)::
+param:name-default=(`show` | `hide`) vtype:[optional string]::
By default, show or hide all the names. This sets the
default value of all the parameters which start with `name-`.
-param:name-header=(`yes` | `no`) (boolean)::
+param:name-header=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the field names in the header scopes.
-param:name-payload=(`yes` | `no`) (boolean)::
+param:name-payload=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the field names in the event payload scopes.
-param:name-scope=(`yes` | `no`) (boolean)::
+param:name-scope=(`yes` | `no`) vtype:[optional boolean]::
Show or hide the scope names.
-param:no-delta=`yes` (boolean)::
+param:no-delta=`yes` vtype:[optional boolean]::
Do not print the time delta between consecutive lines.
-param:path='PATH' (string)::
+param:path='PATH' vtype:[optional string]::
Print the text output to the file 'PATH' instead of the standard
output.
-param:verbose=`yes` (boolean)::
+param:verbose=`yes` vtype:[optional boolean]::
Turn the verbose mode on.
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- event notifications to pretty-print.
+== PORTS
+
+----
++------------------+
+| sink.text.pretty |
+| |
+@ in |
++------------------+
+----
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+=== Input
+
+`in`::
+ Single input port.
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+== ENVIRONMENT VARIABLES
+
+include::common-common-env.txt[]
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-text(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-text(7)
-babeltrace2-sink.utils.counter(7)
-================================
+= babeltrace2-sink.utils.counter(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-sink.utils.counter - Babeltrace's notification counter sink
+== NAME
+
+babeltrace2-sink.utils.counter - Babeltrace 2's message counter sink
component class
-DESCRIPTION
------------
-The Babeltrace compcls:sink.utils.counter component class, provided by
-the man:babeltrace2-plugin-utils(7) plugin, once instantiated, prints to
-the standard output the number of notifications it receives on its input
-port, with a count for each type.
+== DESCRIPTION
+
+A Babeltrace~2 compcls:sink.utils.counter component prints to the
+standard output the number of messages it consumes with a count for each
+type.
+
+----
+ +--------------------+
+ | sink.utils.counter |
+ | +--> Statistics to the
+Messages -->@ in | standard output
+ +--------------------+
+----
+
+include::common-see-babeltrace2-intro.txt[]
The component's output looks like this:
----
- 664891 events
- 12 stream beginnings
- 0 stream ends
- 93 packet beginnings
- 81 packet ends
- 0 inactivities
- 6 discarded events notifications
- 375378 known discarded events
- 2 discarded packets notifications
- 5 known discarded packets
- 1040455 notifications (TOTAL)
+ 3842964 Event messages
+ 4 Stream beginning messages
+ 1 Stream end messages
+ 18 Packet beginning messages
+ 14 Packet end messages
+ 189 Discarded event messages
+ 0 Discarded packet messages
+ 3 Message iterator inactivity messages
+ 3843000 messages (TOTAL)
----
By default, a compcls:sink.utils.counter component prints a new block of
-statistics every 1000 received notifications, whatever their types. You
-can use the param:step parameter to override this default period.
+statistics every 1000 consumed messages, whatever their types. You can
+use the param:step parameter to override this default period.
The component always prints a block of statistics when there's no more
-notifications to receive from its input port and the last block was
-different.
+messages to consume from its upstream message iterator and the last
+block was different.
By default, a compcls:sink.utils.counter component prints the count of
-notifications for each type, even if this count is 0. You can make it
-hide the zero counts with the param:hide-zero parameter.
+messages for each type, even if this count is 0. You can make it hide
+the zero counts with the param:hide-zero parameter.
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
+== INITIALIZATION PARAMETERS
-param:hide-zero=`yes` (boolean)::
+param:hide-zero=`yes` vtype:[optional boolean]::
Do not print the statistics lines where the count is zero.
-param:step='STEP' (integer)::
- Print a new block of statistics every 'STEP' received notifications
- instead of 1000. If 'STEP' is 0, then the component only prints
- statistics when there's no more notifications to receive.
+param:step='STEP' vtype:[optional unsigned integer]::
+ Print a new block of statistics every 'STEP' consumed messages
+ instead of 1000.
++
+If 'STEP' is 0, then the component only prints statistics when there's
+no more messages to consume.
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications to count.
+== PORTS
+----
++--------------------+
+| sink.utils.counter |
+| |
+@ in |
++--------------------+
+----
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+=== Input
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+`in`::
+ Single input port.
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-utils(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-utils(7)
-babeltrace2-sink.utils.dummy(7)
-==============================
+= babeltrace2-sink.utils.dummy(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-sink.utils.dummy - Babeltrace's dummy sink component class
+== NAME
+babeltrace2-sink.utils.dummy - Babeltrace 2's dummy sink component class
-DESCRIPTION
------------
-The Babeltrace compcls:sink.utils.dummy component class, provided by the
-man:babeltrace2-plugin-utils(7) plugin, once instantiated, receives
-notifications from its input port and discards them (does absolutely
-nothing with them).
-A compcls:sink.utils.dummy sink component can be useful to run a trace
-processing graph with no sink side effect, for example to perform
-benchmarks. You should prefer this component class for such tasks
-instead of, for example, using a compcls:sink.text.pretty component and
-sending its output to `/dev/null`, as a compcls:sink.text.pretty
-component still performs pretty-printing operations.
+== DESCRIPTION
+A Babeltrace~2 compcls:sink.utils.dummy component consumes messages
+and discards them (does absolutely nothing with them).
-INITIALIZATION PARAMETERS
--------------------------
-This component class has no initialization parameters.
+----
+ +------------------+
+ | sink.utils.dummy |
+ | |
+Messages -->@ in |
+ +------------------+
+----
+include::common-see-babeltrace2-intro.txt[]
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications to discard.
+A compcls:sink.utils.dummy sink component can be useful to run a trace
+processing graph with no sink side effect, for example to perform
+benchmarks. Prefer a compcls:sink.utils.dummy component class for such
+tasks to, for example, a compcls:sink.text.pretty component and sending
+its output to `/dev/null`, as a compcls:sink.text.pretty component still
+performs formatting operations.
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+== PORTS
+----
++------------------+
+| sink.utils.dummy |
+| |
+@ in |
++------------------+
+----
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+
+=== Input
+
+`in`::
+ Single input port.
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-utils(7),
-man:babeltrace2-intro(7)
+== SEE ALSO
+
+man:babeltrace2-intro(7),
+man:babeltrace2-plugin-utils(7)
-babeltrace2-source.ctf.fs(7)
-===========================
+= babeltrace2-source.ctf.fs(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-source.ctf.fs - Babeltrace's file system CTF source
+== NAME
+
+babeltrace2-source.ctf.fs - Babeltrace 2's file system CTF source
component class
-DESCRIPTION
------------
-The Babeltrace compcls:source.ctf.fs component class, provided by the
-man:babeltrace2-plugin-ctf(7) plugin, once instantiated, opens one or
-more http://diamon.org/ctf/[CTF] traces on the file system and emits the
-notifications of their data streams on its output ports.
+== DESCRIPTION
+A Babeltrace~2 compcls:source.ctf.fs message iterator reads one or
+more https://diamon.org/ctf/[CTF]~1.8 streams on the file system
+and emits corresponding messages.
-Operation
-~~~~~~~~~
-A compcls:source.ctf.fs component recurses the directory given by the
-param:path parameter to find CTF traces. Note that, since a CTF trace
-directory cannot contain another CTF trace, if you need to open a single
-trace, set the param:path parameter to a directory which directly
-contains the `metadata` file.
+----
+CTF streams on
+the file system
+ |
+ | +---------------------+
+ | | src.ctf.fs |
+ | | |
+ '-->| ...5c847 | 0 | 0 @--> Stream 0 messages
+ | ...5c847 | 0 | 1 @--> Stream 1 messages
+ | ...5c847 | 0 | 2 @--> Stream 2 messages
+ +---------------------+
+----
-For each trace, the component creates one output port per effective data
-stream. Multiple data stream files can constitute a single effective
-data stream. The name of a data stream output port is the absolute path
-to the corresponding data stream file, or to one of the corresponding
-data stream files if there's more than one.
+include::common-see-babeltrace2-intro.txt[]
-The component skips the following files when looking for data stream
-files:
-* Any file which starts with `.`, including subdirectories.
-* Any non-regular file.
+[[input]]
+=== Input
+A compcls:source.ctf.fs component opens a single _logical_ CTF trace. A
+logical CTF trace contains one or more _physical_ CTF traces. A physical
+CTF trace on the file system is a directory which contains:
-[[trace-naming]]
-Trace naming
-~~~~~~~~~~~~
-A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`,
-with:
+* One metadata stream file named `metadata`.
+* One or more data stream files, that is, any file with a name that does
+ not start with `.` and which is not `metadata`.
+* **Optional**: One https://lttng.org/[LTTng] index directory named
+ `index`.
-`HOSTNAME`::
- Value of the trace's `hostname` environment constant. If this
- environment constant does not exist, or if its value is not a
- string, then this part is omitted.
+If the logical CTF trace to handle contains more than one physical CTF
+trace, then all the physical CTF traces must have a trace UUID and all
+UUIDs must be the same. Opening more than one physical CTF trace to
+constitute a single logical CTF trace is needed to support LTTng's
+tracing session rotation feature, for example (see man:lttng-rotate(1)
+starting from LTTng~2.11).
-`PATH`::
- Relative path to the trace, starting at and including the basename
- of the param:path parameter. This path is normalized, that is, it
- doesn't contain path elements named `..` or `.`.
+You specify which physical CTF traces to open and read with the
+param:inputs array parameter. Each entry in this array is the path to a
+physical CTF trace directory, that is, the directory directly containing
+the stream files.
-For example, assume the following hierarchy:
+A compcls:source.ctf.fs component does not recurse into directories to
+find CTF traces. However, the component class provides the
+`babeltrace.support-info` query object which indicates whether or not a
+given directory looks like a CTF trace directory (see
+<<support-info,```babeltrace.support-info`''>>).
-----
-/
- home/
- user/
- my-traces/
- trace1/
- metadata
- ...
- node-traces/
- server/
- metadata
- ...
- client/
- metadata
- ...
-----
+The component creates one output port for each logical CTF data stream.
+More than one physical CTF data stream file can support a single logical
+CTF data stream (LTTng's trace file rotation and tracing session
+rotation can cause this).
-If you set the param:path parameter to `/home/user/my-traces`, and
-assuming the hostname of the `trace1` and `server` traces is `machine`,
-and the hostname of the `client` trace is `embedded`, then the trace
-names are:
-* `machine/my-traces/trace1`
-* `machine/my-traces/node-traces/server`
-* `embedded/my-traces/node-traces/client`
+=== Trace quirks
+Many tracers produce CTF traces. A compcls:source.ctf.fs component makes
+some effort to support as many CTF traces as possible, even those with
+malformed streams.
-Metadata quirks
-~~~~~~~~~~~~~~~
-A compcls:source.ctf.fs component makes some efforts to support as many
-CTF traces as possible, even those of which the metadata is malformed
-or implements specification bugs.
+Generally:
-In particular:
+* If the `timestamp_begin` or `timestamp_end` packet context field class
+ exists, but it is not mapped to a clock class, and there's only one
+ clock class at this point in the metadata stream, the component maps
+ the field class to this unique clock class.
-* If the component detects that the trace was produced by LTTng, it sets
- the `monotonic` clock class as absolute so that different LTTng traces
- are directly correlatable. An LTTng trace has its `tracer_name`
- environment constant starting with `lttng`.
+A compcls:source.ctf.fs component has special quirk handling for some
+https://lttng.org/[LTTng] and https://lttng.org/[barectf] traces,
+depending on the tracer's version:
-* If the `timestamp_begin` or `timestamp_end` packet context field
- type exists, but it is not mapped to a clock class, and there's
- only one clock class at this point in the metadata stream, the
- component maps it to this unique clock class.
+All LTTng versions::
++
+--
+* The component sets the `monotonic` clock class's origin to the Unix
+ epoch so that different LTTng traces are always correlatable.
++
+This is the equivalent of setting the
+param:force-clock-class-origin-unix-epoch parameter to true.
-* If an enumeration field type's label starts with `_`, the component
- removes the starting `_` character. This is needed to accomodate
- an eventual variant field type which refers to the enumeration field type
- as its tag and which has equivalent choice names also starting
- with `_` (the `_` must be removed from field and choice names as
- per CTF{nbsp}1.8.2).
+* For a given data stream, for all the contiguous last packets of which
+ the `timestamp_end` context field is 0, the message iterator uses the
+ packet's last event record's time as the packet end message's time.
++
+This is useful for the traces which man:lttng-crash(1) generates.
+--
+
+LTTng-UST up to, but excluding, 2.11.0::
+LTTng-modules up to, but excluding, 2.9.13::
+LTTng-modules from 2.10.0 to 2.10.9::
++
+--
+* For a given packet, the message iterator uses the packet's last
+ event record's time as the packet end message's time, ignoring the
+ packet context's `timestamp_end` field.
+--
+
+barectf up to, but excluding, 2.3.1::
++
+--
+* For a given packet, the message iterator uses the packet's first event
+ record's time as the packet beginning message's time, ignoring the
+ packet context's `timestamp_begin` field.
+--
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional unless indicated otherwise.
+== INITIALIZATION PARAMETERS
-param:clock-class-offset-ns (integer)::
- Value to add, in nanoseconds, to the offset of all the clock classes
- that the component creates.
+param:clock-class-offset-ns='NS' vtype:[optional signed integer]::
+ Add 'NS' nanoseconds to the offset of all the clock classes that the
+ component creates.
+
You can combine this parameter with the param:clock-class-offset-s
parameter.
-param:clock-class-offset-s (integer)::
- Value to add, in seconds, to the offset of all the clock classes
- that the component creates.
+param:clock-class-offset-s='SEC' vtype:[optional signed integer]::
+ Add 'SEC' seconds to the offset of all the clock classes that the
+ component creates.
+
You can combine this parameter with the param:clock-class-offset-ns
parameter.
-param:path='PATH' (string, mandatory)::
- Path to the directory to recurse for CTF traces.
+param:force-clock-class-origin-unix-epoch=`yes` vtype:[optional boolean]::
+ Force the origin of all clock classes that the component creates to
+ have a Unix epoch origin, whatever the detected tracer.
+param:inputs='DIRS' vtype:[array of strings]::
+ Open and read the physical CTF traces located in 'DIRS'.
++
+Each element of 'DIRS' is the path to a physical CTF trace directory
+containing the trace's stream files.
++
+All the specified physical CTF traces must belong to the same logical
+CTF trace. See <<input,``Input''>> to learn more about logical and
+physical CTF traces.
-PORTS
------
-Output
-~~~~~~
-For each opened trace, the component creates one output port for each
-effective data stream. The name of a data stream output port is the
-normalized (no `..` or `.` elements) absolute path to the corresponding
-data stream file, or to one of the corresponding data stream files if
-there's more than one.
+param:trace-name='NAME' vtype:[optional string]::
+ Set the name of the trace object that the component creates to
+ 'NAME'.
-QUERY OBJECTS
--------------
-`metadata-info`
-~~~~~~~~~~~~~~~
-You can query the `metadata-info` object for a specific CTF trace to get
-its plain text metadata stream as well as whether or not it is
-packetized.
+== PORTS
-Parameters:
+----
++--------------------+
+| src.ctf.fs |
+| |
+| ...5c847 | 0 | 1 @
+| ... @
++--------------------+
+----
-`path` (string, mandatory)::
- Path to the CTF trace directory which contains the `metadata` file.
-Returned object (map):
+=== Output
-`text` (string)::
- Plain text metadata.
+A compcls:source.ctf.fs component creates one output port for each
+logical CTF data stream. See <<input,``Input''>> to learn more about
+logical and physical CTF data streams.
-`is-packetized` (boolean)::
- True if the metadata stream is packetized.
+Each output port's name has one of the following forms:
+[verse]
+__TRACE-ID__ | __STREAM-CLASS-ID__ | __STREAM-ID__
+__TRACE-ID__ | __STREAM-ID__
-`babeltrace.trace-info`
-~~~~~~~~~~~~~~~~~~~~~~~
-You can query the `babeltrace.trace-info` object for a set of CTF traces
-to get information about the data streams they contain, their
-intersection time range, and more.
+The component uses the second form when the stream class ID is not
+available.
-This query object requires that the processed CTF traces have the
-`timestamp_begin` and `timestamp_end` fields in their packet context
-field types.
+__TRACE-ID__::
+ Trace's UUID if available, otherwise trace's absolute directory
+ path.
-Parameters:
+__STREAM-CLASS-ID__::
+ Stream class ID.
-`path` (string, mandatory)::
- Path to a directory to recurse to find CTF traces.
+__STREAM-ID__::
+ Stream ID if available, otherwise stream's absolute file path.
-Returned object (array of maps, one element for each found trace):
-`name` (string)::
- Trace name, as per the explanations in the <<trace-naming,Trace
- naming>> section.
+[[query-objs]]
+== QUERY OBJECTS
-`path` (string)::
- Trace path.
+[[support-info]]
+=== `babeltrace.support-info`
-`range-ns` (map)::
- Full time range of the trace.
-+
---
-`begin` (integer)::
- Beginning time (ns since Epoch) of the trace.
+See man:babeltrace2-query-babeltrace.support-info(7) to learn more
+about this query object.
-`end` (integer)::
- End time (ns since Epoch) of the trace.
---
+For a directory input which is the path to a CTF trace directory,
+the result object contains:
-`intersection-range-ns` (map)::
- This entry only exists if there is a data stream intersection range.
-+
---
-`begin` (integer)::
- Beginning time (ns since Epoch) of the trace's data stream
- intersection.
+nlqres:weight::
+ 0.75
-`end` (integer)::
- End time (ns since Epoch) of the trace's data stream intersection.
---
+nlqres:group::
+ Trace's UUID if available, otherwise the entry does not exist.
-`streams` (array of maps, one element for each trace's effective data stream)::
-+
---
-`paths` (array of strings)::
- Absolute paths to the data stream files which are part of this
- data stream.
+You can leverage this query object's nlqres:group entry to assemble many
+physical CTF traces as a single logical CTF trace (see
+<<input,``Input''>> to learn more about logical and physical CTF
+traces). This is how the man:babeltrace2-convert(1) command makes it
+possible to specify as non-option arguments the paths to multiple
+physical CTF traces which belong to the same logical CTF trace and
+create a single compcls:source.ctf.fs component.
-`class-id` (integer)::
- Numeric ID of the data stream's class.
-`range-ns` (map)::
- Full time range of the data stream.
-+
---
-`begin` (integer)::
- Beginning time (ns since Epoch) of the data stream.
+=== `babeltrace.trace-infos`
-`end` (integer)::
- End time (ns since Epoch) of the data stream.
---
---
+See man:babeltrace2-query-babeltrace.trace-infos(7) to learn more
+about this query object.
+
+
+=== `metadata-info`
+
+You can query the `metadata-info` object for a specific CTF trace to get
+its plain text metadata stream as well as whether or not it is
+packetized.
-ENVIRONMENT VARIABLES
----------------------
-include::common-ctf-plugin-env.txt[]
+Parameters:
+
+nlparam:path='PATH' vtype:[string]::
+ Path to the physical CTF trace directory which contains the
+ `metadata` file.
+Result object (map):
-Component class
-~~~~~~~~~~~~~~~
-include::common-common-compat-env.txt[]
+qres:is-packetized vtype:[boolean]::
+ True if the metadata stream file is packetized.
-`BABELTRACE_SRC_CTF_FS_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
+qres:text vtype:[string]::
+ Plain text metadata stream.
include::common-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
+man:babeltrace2-intro(7),
man:babeltrace2-plugin-ctf(7),
-man:babeltrace2-intro(7)
+man:lttng-crash(1)
-babeltrace2-source.ctf.lttng-live(7)
-===================================
+= babeltrace2-source.ctf.lttng-live(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-source.ctf.lttng-live - Babeltrace's LTTng live source
+== NAME
+
+babeltrace2-source.ctf.lttng-live - Babeltrace 2's LTTng live source
component class
-DESCRIPTION
------------
-The Babeltrace compcls:source.ctf.lttng-live source component class,
-provided by the man:babeltrace2-plugin-ctf(7) plugin, once instantiated,
-connects to a local or remote http://lttng.org/[LTTng] relay daemon and
-emits the received notifications on its output ports. More information
-about LTTng live is available in the
-http://lttng.org/docs/#doc-lttng-live[LTTng Documentation].
+== DESCRIPTION
-A compcls:source.ctf.lttng-live component handles the notifications of
-one, and only one LTTng tracing session. A single LTTng tracing session
-can contain one or more traces, depending on the active tracing domains
-and the configured user space buffering scheme.
+A Babeltrace~2 compcls:source.ctf.lttng-live message iterator
+connects to a local or remote https://lttng.org/[LTTng] relay daemon,
+receives the streams of a specific tracing session, and emits
+corresponding messages.
-The component connects to an LTTng relay daemon using the param:url
-parameter.
+----
+CTF streams over
+LTTng live (TCP)
+ |
+ | +--------------------+
+ | | src.ctf.lttng-live |
+ '-->| |
+ | out @--> Sorted messages of one
+ +--------------------+ or more streams
+----
-For each trace, the component creates one output port per effective data
-stream. The name of a data stream output port is `stream-` followed by
-its unique LTTng live ID within the tracing session.
+More information about LTTng live is available in the
+https://lttng.org/docs/#doc-lttng-live[LTTng Documentation].
-The component names each trace `[HOSTNAME/]SESSION/PATH`, with:
+include::common-see-babeltrace2-intro.txt[]
-`HOSTNAME`::
- Value of the trace's `hostname` environment constant. If this
- environment constant does not exist, or if its value is not a
- string, then this part is omitted.
+A compcls:source.ctf.lttng-live component has a single output port: its
+message iterator muxes (sorts) the messages from the various CTF data
+streams internally.
-`SESSION`::
- Tracing session name.
+A compcls:source.ctf.lttng-live message iterator handles the messages of
+one, and only one LTTng tracing session. A single LTTng tracing session
+can contain one or more traces, depending on the active tracing domains
+and the configured user space buffering scheme.
-`PATH`::
- Other path elements up to the trace directory containing the
- `metadata` file from the LTTng relay daemon's point of view.
- For example:
-+
-----
-kernel
-----
-+
-----
-ust/uid/1000/64-bit
-----
+The component connects to an LTTng relay daemon using the param:inputs
+parameter. This is an array of exactly one string which is the URL of
+the LTTng relay daemon to connect to.
-For example:
+By default, if the remote tracing session name does not exist, the
+message iterator returns "try again later". This default mode makes the
+message iterator never end: even if the remote tracing session is
+destroyed, the message iterator keeps on waiting for a tracing session
+with the same name to exist. You can change this behaviour with the
+param:session-not-found-action initialization parameter.
-----
-myhost/auto-20150909-223909/ust/uid/1000/64-bit
-----
+NOTE: As of this version, you can only create one message iterator per
+compcls:source.ctf.lttng-live component. This is because the LTTng live
+protocol accepts at most one client per tracing session per LTTng relay
+daemon.
-A compcls:source.ctf.lttng-live never blocks: it asks the downstream
-component to try again later instead.
+== INITIALIZATION PARAMETERS
-INITIALIZATION PARAMETERS
--------------------------
-param:url='URL' (string, mandatory)::
- The URL to use to connect to the LTTng relay daemon. The format
- of 'URL' is:
+param:inputs='URL' vtype:[array of one string]::
+ Use 'URL' to connect to the LTTng relay daemon.
++
+'URL' is an array of exactly one string of which the format is:
+
--
[verse]
LTTng relay daemon's host name or IP address.
'RDPORT'::
- LTTng relay daemon's listening port. If not specified, the default
- port, 5344, is used.
+ LTTng relay daemon's listening port.
++
+If not specified, the component uses the default port ({defrdport}).
'TGTHOST'::
Target's host name or IP address.
Name of the LTTng tracing session from which to receive data.
--
+param:session-not-found-action=(`continue` | `fail` | `end`) vtype:[optional string]::
+ When the message iterator does not find the specified remote tracing
+ session ('SESSION' part of the param:inputs parameter), do one of:
++
+--
+`continue` (default)::
+ Keep on trying, returning "try again later" to the downstream user
+ until the tracing session exists.
++
+With this action, the message iterator never ends, as the LTTng live
+protocol cannot currently indicate that a tracing session will never
+exist.
+
+`fail`::
+ Fail.
-PORTS
------
-Output
-~~~~~~
-When you create the component, its only output port is `no-stream`. This
-port exists as long as there is no data stream output port. The port
-only asks the downstream component to try again later.
+`end`::
+ End.
+--
-For each received LTTng trace, the component creates one output port for
-each effective data stream. The name of a data stream output port is
-`stream-ID`, where `ID` is a unique LTTng live ID within the tracing
-session.
+== PORTS
+
+----
++--------------------+
+| src.ctf.lttng-live |
+| |
+| out @
++--------------------+
+----
+
+
+=== Output
+
+`out`::
+ Single output port.
+
+
+== QUERY OBJECTS
+
+=== `babeltrace.support-info`
+
+See man:babeltrace2-query-babeltrace.support-info(7) to learn more
+about this query object.
+
+For a string input which honors the LTTng live URL format (see the
+param:inputs parameter), the result object is 0.75.
+
+
+=== `sessions`
-QUERY OBJECTS
--------------
-`sessions`
-~~~~~~~~~~
You can query the `sessions` object to get a list of available LTTng
-live tracing sessions for a given LTTng relay daemon URL.
+tracing sessions for a given LTTng relay daemon URL.
Parameters:
-`url` (string, mandatory)::
- The URL to use to connect to the LTTng relay daemon. The format
- of 'URL' is:
+nlparam:url='URL' vtype:[string]::
+ Use 'URL' to connect to the LTTng relay daemon.
++
+The format of 'URL' is:
+
--
[verse]
LTTng relay daemon's host name or IP address.
'RDPORT'::
- LTTng relay daemon's listening port. If not specified, the default
- port, 5344, is used.
+ LTTng relay daemon's listening port.
++
+If not specified, the query operation uses the default port
+({defrdport}).
--
-Returned object (array of maps, one element for each tracing session):
-
-`url` (string)::
- URL to use as the param:url parameter to connect to the same LTTng
- relay daemon and receive data from this tracing session.
-
-`target-hostname` (string)::
- Hostname of the tracing session. This is not necessarily the
- relay daemon's hostname.
+Result object (array of maps, one element for each available tracing
+session):
-`session-name` (string)::
- Tracing session's name.
-
-`timer-us` (integer)::
- Tracing session's configured live timer (µs)
- (see man:lttng-create(1)).
-
-`stream-count` (integer)::
- Current number of streams in this tracing sessions, including the
- metadata streams.
-
-`client-count` (integer)::
+qres:client-count vtype:[unsigned integer]::
Current number of LTTng live clients connected to the relay daemon
to receive data from this tracing session.
+qres:session-name vtype:[string]::
+ Tracing session's name.
-LIMITATIONS
------------
-A compcls:source.ctf.lttng-live component only accepts a connection
-to one of its output port if all its output ports are connected to the
-input ports of the same downstream component.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-ctf-plugin-env.txt[]
+qres:stream-count vtype:[unsigned integer]::
+ Current number of CTF streams in this tracing sessions, including
+ the metadata streams.
+qres:target-hostname vtype:[string]::
+ Hostname of the tracing session.
++
+This is not necessarily the relay daemon's hostname.
-Component class
-~~~~~~~~~~~~~~~
-include::common-common-compat-env.txt[]
+qres:timer-us vtype:[unsigned integer]::
+ Tracing session's configured live timer's period (µs)
+ (see man:lttng-create(1)).
-`BABELTRACE_SRC_CTF_LTTNG_LIVE_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
+qres:url vtype:[string]::
+ URL to use as the first element of the param:inputs parameter to
+ connect to the same LTTng relay daemon and receive data from this
+ tracing session.
include::common-footer.txt[]
-SEE ALSO
---------
-man:babeltrace2-plugin-ctf(7),
+== SEE ALSO
+
man:babeltrace2-intro(7),
+man:babeltrace2-plugin-ctf(7),
man:lttng-relayd(8),
man:lttng-create(1)
-babeltrace2-source.text.dmesg(7)
-===============================
+= babeltrace2-source.text.dmesg(7)
:manpagetype: component class
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
-babeltrace2-source.text.dmesg - Babeltrace's Linux kernel ring buffer
+== NAME
+
+babeltrace2-source.text.dmesg - Babeltrace 2's Linux kernel ring buffer
source component class
-DESCRIPTION
------------
-The Babeltrace compcls:source.text.dmesg component class, provided by
-the man:babeltrace2-plugin-text(7) plugin, once instantiated, reads the
+== DESCRIPTION
+
+A Babeltrace~2 compcls:source.text.dmesg message iterator reads the
lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)
-tool, and emits corresponding event notifications on its output port.
+tool, and emits corresponding event messages.
+
+----
+Linux kernel ring buffer
+lines (file or standard input)
+ |
+ | +----------------+
+ | | src.text.dmesg |
+ '-->| |
+ | out @--> Messages (single stream)
+ +----------------+
+----
-The events created by a compcls:source.text.dmesg component are named
-`string` and contain a single payload string field named `str` which
-contains the corresponding ring buffer line.
+include::common-see-babeltrace2-intro.txt[]
-By default, a compcls:source.text.dmesg component reads the lines of the
-standard input stream. You can make the component read the lines of a
-text file instead with the param:path parameter.
+A compcls:source.text.dmesg message iterator names the events it creates
+`string`. Each event contain a single payload string field named `str`
+which contains the corresponding ring buffer line.
-By default, the component tries to extract the timestamps of the kernel
-ring buffer lines and use them as the created events's timestamps. A
-typical man:dmesg(1) line looks like this:
+By default, a compcls:source.text.dmesg message iterator reads the lines
+of the standard input stream. You can make the message iterator read the
+lines of a text file instead with the param:path parameter.
+
+By default, the message iterator tries to extract the timestamps of the
+kernel ring buffer lines and use them as the created events's
+timestamps. A typical man:dmesg(1) line looks like this:
----
[87166.510937] PM: Finishing wakeup.
----
-In the last example, the `[87166.510937]` part is the timestamp to
-extract. You can make the component not extract timestamps from lines
-with the param:no-extract-timestamp parameter.
+The `[87166.510937]` part is the timestamp to extract. When this
+information is available, the component creates a clock class which does
+:not: have the Unix epoch as its origin.
+
+You can make the message iterator not extract timestamps from lines with
+the param:no-extract-timestamp parameter.
+[NOTE]
+====
+It is possible that the output of man:dmesg(1) contains unsorted lines,
+that is, their timestamps go back in time. You can see this with the
+nlopt:--show-delta option of man:dmesg(1): some time differences can be
+negative.
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
+This is due to a https://lwn.net/Articles/780556/[2019 change] to the
+kernel's ring buffer API.
-param:no-extract-timestamp=`yes` (boolean)::
+As of this version, a compcls:source.text.dmesg message iterator
+requires that the input kernel ring buffer lines be sorted by timestamp
+(when they have timestamps), failing otherwise.
+====
+
+
+== INITIALIZATION PARAMETERS
+
+param:no-extract-timestamp=`yes` vtype:[optional boolean]::
Do :not: extract timestamps from the kernel ring buffer lines: set
the created event's payload's `str` field to the whole line,
including any timestamp prefix.
-param:path='PATH' (string)::
+param:path='PATH' vtype:[optional string]::
Read the kernel ring buffer lines from the file 'PATH' instead of
the standard input stream.
-PORTS
------
-Output
-~~~~~~
-`out`::
- Single output port to which the component sends the created
- notifications.
+== PORTS
+----
++----------------+
+| src.text.dmesg |
+| |
+| out @
++----------------+
+----
-QUERY OBJECTS
--------------
-This component class has no objects to query.
+=== Output
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
+`out`::
+ Single output port.
include::common-footer.txt[]
-SEE ALSO
---------
+== SEE ALSO
+
man:babeltrace2-plugin-text(7),
man:babeltrace2-intro(7)
-babeltrace2(1)
-=============
+= babeltrace2(1)
:manpagetype: program
-:revdate: 5 October 2017
+:revdate: 14 September 2019
-NAME
-----
+== NAME
+
babeltrace2 - Convert or process one or more traces, and more
-SYNOPSIS
---------
+== SYNOPSIS
+
[verse]
-*babeltrace2* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] ['<<commands,CMD>>'] ['CMD ARGS']
+*babeltrace2* [opt:--debug | opt:--verbose | opt:--log-level='LVL']
+ [opt:--omit-home-plugin-path] [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...] ['<<commands,CMD>>'] ['CMD ARGS']
+
+
+== DESCRIPTION
+
+`babeltrace2` is an open-source trace converter and processor
+command-line program. The tool can open one or more traces and convert
+between multiple formats, possibly with one or more filters in the
+conversion path, and perform other operations depending on the
+command 'CMD' (see <<commands,``COMMANDS''>>).
+[NOTE]
+--
+You might be looking for the man:babeltrace2-convert(1) command's
+manual page; the `convert` command is the default command of
+`babeltrace2` and is backward compatible with man:babeltrace(1).
-DESCRIPTION
------------
-`babeltrace2` is an open-source trace converter and processor. The tool
-can convert from one trace format to another, possibly with one or more
-filters in the conversion path, and perform other operations depending
-on the command 'CMD'.
+See <<examples,``EXAMPLES''>> for `convert` command examples.
+--
-See man:babeltrace2-intro(7) to learn more about the Babeltrace
-project and its core concepts.
+include::common-see-babeltrace2-intro.txt[]
-Most of the `babeltrace2` commands load Babeltrace plugins to perform
-their operation. The search path for Babeltrace plugins is, in this
-order:
+Most of the `babeltrace2` commands load Babeltrace~2 plugins to
+perform their operation. The search path for Babeltrace~2 plugins
+is, in this order:
-. The colon-separated list of directories in the
- `BABELTRACE_PLUGIN_PATH` environment variable.
+. The colon-separated (or semicolon, on Windows) list of directories in
+ the `BABELTRACE_PLUGIN_PATH` environment variable.
-. The colon-separated list of directories in the specific command's
- nlopt:--plugin-path option.
+. The colon-separated (or semicolon, on Windows) list of directories in
+ the opt:--plugin-path option.
. `$HOME/.local/lib/babeltrace2/plugins`
. +{system_plugin_path}+
You can use the man:babeltrace2-list-plugins(1) command to dynamically
-list the available plugins and what they offer. See <<plugins,PLUGINS>>
-for a list of plugins shipped with Babeltrace.
+list the available plugins and what they offer. See
+<<plugins,``PROJECT'S PLUGINS''>> for a list of plugins shipped with
+Babeltrace~2.
-OPTIONS
--------
-opt:-d, opt:--debug::
- Turn the debugging mode on.
-+
-This is equivalent to opt:--log-level=`TRACE`.
+== OPTIONS
-opt:-l 'LVL', opt:--log-level='LVL'::
- Set the log level of all known Babeltrace loggers to 'LVL'. You
- can override the level of a specific logger with a dedicated
- log level environment variable. If you don't specify this option,
- it is equivalent to nlopt:--log-level=`WARNING`.
+opt:-d::
+opt:--debug::
+ Legacy option: this is equivalent to opt:--log-level=`TRACE`.
+
+opt:-l 'LVL'::
+opt:--log-level='LVL'::
+ Set the log level of all known Babeltrace~2 loggers to 'LVL',
+ including individual components for the man:babeltrace2-convert(1)
+ and man:babeltrace2-run(1) commands.
++
+You can override the log level of a specific component with the
+nlopt:--log-level option of the man:babeltrace2-convert(1) or
+man:babeltrace2-run(1) commands.
++
+You can override the log level of the library with the
+`LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable.
++
+You can override the log level of the CLI with the
+`BABELTRACE_CLI_LOG_LEVEL` environment variable.
++
+You can override the log level of the Babeltrace~2 Python bindings
+with the `BABELTRACE_PYTHON_BT2_LOG_LEVEL` environment variable.
+
The available values for 'LVL' are:
+
--
-`NONE`::
-`N`::
- Logging is disabled.
-
-`FATAL`::
-`F`::
- Severe errors that lead the execution to abort immediately. This
- level should be enabled in production.
-
-`ERROR`::
-`E`::
- Errors that might still allow the execution to continue. Usually,
- once one or more errors are reported at this level, the application,
- plugin, or library won't perform any more useful task, but it should
- still exit cleanly. This level should be enabled in production.
-
-`WARN`::
-`WARNING`::
-`W`::
- Potentially harmful situations which still allow the execution
- to continue. This level should be enabled in production.
-
-`INFO`::
-`I`::
- Informational messages that highlight progress or important states
- of the application, plugin, or library. This level can be enabled in
- production.
-
-`DEBUG`::
-`D`::
- Debugging information, with a higher level of details than the
- `TRACE` level. This level should :not: be enabled in production.
-
-`TRACE`::
-`T`::
- Low-level debugging context information. This level should :not: be
- enabled in production.
+include::common-log-levels.txt[]
--
-opt:-v, opt:--verbose::
- Turn the verbose mode on.
+opt:--omit-home-plugin-path::
+ Do not search for plugins in `$HOME/.local/lib/babeltrace2/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 plugins can be found.
+
+opt:-v::
+opt:--verbose::
+ Legacy option: this is equivalent to opt:--log-level=`INFO`.
+
-This is equivalent to opt:--log-level=`INFO`.
+If 'CMD' is `convert` or is missing, then this 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.
+
-opt:-h, opt:--help::
+opt:-h::
+opt:--help::
Show help and quit.
-opt:-V, opt:--version::
+opt:-V::
+opt:--version::
Show version and quit.
[[commands]]
-COMMANDS
---------
+== COMMANDS
+
The following commands also have their own nlopt:--help option.
-man:babeltrace2-convert(1)::
- Build a trace conversion graph and run it.
+`convert`::
+ Convert one or more traces to a given format, possibly with filters
+ in the conversion path.
++
+This is the default command: you don't need to explicitly specify this
+command's name to use it.
++
+This command is backward compatible with the man:babeltrace(1) program.
+
-This is the default command: you don't need to explicitly
-specify this command name to use it.
+See man:babeltrace2-convert(1).
-man:babeltrace2-help(1)::
+`help`::
Get help for a specific plugin or plugin's component class.
++
+See man:babeltrace2-help(1).
-man:babeltrace2-list-plugins(1)::
- List the available Babeltrace plugins and their component classes.
+`list-plugins`::
+ List the available Babeltrace~2 plugins and their component
+ classes.
++
+See man:babeltrace2-list-plugins(1).
-man:babeltrace2-query(1)::
+`query`::
Query an object from a component class.
++
+See man:babeltrace2-query(1).
-man:babeltrace2-run(1)::
+`run`::
Build a trace processing graph and run it.
++
+See man:babeltrace2-run(1).
[[plugins]]
-PLUGINS
--------
-The following plugins are provided by the Babeltrace project itself:
+== PROJECT'S PLUGINS
+
+The following plugins are provided by the Babeltrace~2 project
+itself.
man:babeltrace2-plugin-ctf(7)::
CTF trace input (from the file system and from the LTTng-live
protocol) and output to the file system.
+
-* man:babeltrace2-sink.ctf.fs(7)
+Component classes:
++
* man:babeltrace2-source.ctf.fs(7)
* man:babeltrace2-source.ctf.lttng-live(7)
+* man:babeltrace2-sink.ctf.fs(7)
ifeval::[{enable_debug_info} == 1]
man:babeltrace2-plugin-lttng-utils(7)::
Processing graph utilities for LTTng traces.
+
+Component class:
++
* man:babeltrace2-filter.lttng-utils.debug-info(7)
endif::[]
man:babeltrace2-plugin-text(7)::
- Text input and output.
+ Plain text input and output.
++
+Component classes:
+
-* man:babeltrace2-sink.text.pretty(7)
* man:babeltrace2-source.text.dmesg(7)
+* man:babeltrace2-sink.text.details(7)
+* man:babeltrace2-sink.text.pretty(7)
man:babeltrace2-plugin-utils(7)::
Processing graph utilities.
+
+Component classes:
++
* man:babeltrace2-filter.utils.muxer(7)
* man:babeltrace2-filter.utils.trimmer(7)
* man:babeltrace2-sink.utils.counter(7)
* man:babeltrace2-sink.utils.dummy(7)
+[[examples]]
+== EXAMPLES
+
+The following examples are the same as the man:babeltrace2-convert(1)
+manual page's examples because `convert` is the default `babeltrace2`
+program's command.
+
+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-convert(1),
man:babeltrace2-help(1),
man:babeltrace2-list-plugins(1),
man:babeltrace2-query(1),
-man:babeltrace2-run(1),
-man:babeltrace2-intro(7)
+man:babeltrace2-run(1)
+[specialcharacters]
+
+# LaTeX-like non-breaking space (disables subscript but we don't need it)
+~= 
+
[macros]
# command-line option in another man page macro
# Usage: param:param-name
(?su)[\\]?(?P<name>param):(?P<pname>[a-zA-Z0-9_:.-]+(?<![:.]))=
+# no link query result object entry macro
+#
+# Usage: nlqres:qres-name
+(?su)[\\]?(?P<name>nlqres):(?P<pname>[a-zA-Z0-9_:.-]+(?<![:.]))=
+
+# query result object entry macro
+#
+# Usage: qres:qres-name
+(?su)[\\]?(?P<name>qres):(?P<pname>[a-zA-Z0-9_:.-]+(?<![:.]))=
+
# component class specification macro
#
# Usage: compcls:TYPE.PLUGIN.COMPCLS
(?su)[\\]?(?P<name>compcls):(?P<cctype>[a-zA-Z0-9_-]+)\.(?P<ccplug>[a-zA-Z0-9_-]+)\.(?P<ccname>[a-zA-Z0-9_-]+)=
-# not macro
+# value object type
+#
+# Usage: vtype:[TYPE]
+(?su)[\\]?(?P<name>vtype):\[(?P<type>[^\]]+)\]=
+
+# not macro (emphasis)
#
# Usage: :not:
:not:=not
+# all macro (emphasis)
+#
+# Usage: :all:
+:all:=all
+
# escstar macro
#
# Usage: :escstar:
# Usage: :bs:
:bs:=bs
-# man macro expansions
+# macro expansions for DocBook backend (begin)
ifdef::doctype-manpage[]
ifdef::backend-docbook[]
+
+# man macro expansions
[man-inlinemacro]
<citerefentry>
<refentrytitle>{target}</refentrytitle><manvolnum>{section}</manvolnum>
</citerefentry>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# no link option macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[nlopt-inlinemacro]
<literal>{opt}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# command-line option macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[opt-inlinemacro]
<literal>{opt}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# command-line option in another man page macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[manopt-inlinemacro]
<literal>{opt}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# component class initialization parameter macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[param-inlinemacro]
<literal>{pname}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# no link component class initialization parameter macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[nlparam-inlinemacro]
<literal>{pname}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
+
+# query result entry macro expansions
+[qres-inlinemacro]
+<literal>{pname}</literal>
+
+# no link query result entry macro expansions
+[nlqres-inlinemacro]
+<literal>{pname}</literal>
# component class initialization parameter in another man page macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[manparam-inlinemacro]
<literal>{pname}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# component class specification macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[compcls-inlinemacro]
<literal>{cctype}.{ccplug}.{ccname}</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
+
+# value object type macro expansions
+[vtype-inlinemacro]
+[{type}]
# not macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[not-inlinemacro]
NOT
-endif::backend-docbook[]
-endif::doctype-manpage[]
+
+# all macro expansions
+[all-inlinemacro]
+ALL
# escstar macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[escstar-inlinemacro]
<literal>\e*</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# esccomma macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[esccomma-inlinemacro]
<literal>\e,</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# escdot macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[escdot-inlinemacro]
<literal>\e,</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# bs macro expansions
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[bs-inlinemacro]
<literal>\e</literal>
-endif::backend-docbook[]
-endif::doctype-manpage[]
# configure XML man page header
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
[header]
template::[header-declarations]
<refentry>
<manvolnum>{manvolnum}</manvolnum>
<refmiscinfo class="source">Babeltrace</refmiscinfo>
<refmiscinfo class="version">{babeltrace_version}</refmiscinfo>
- <refmiscinfo class="manual">Babeltrace manual</refmiscinfo>
+ <refmiscinfo class="manual">Babeltrace 2 manual</refmiscinfo>
</refmeta>
<refnamediv>
<refname>{manname}</refname>
<refpurpose>{manpurpose}</refpurpose>
</refnamediv>
+
+# macro expansions for DocBook backend (end)
endif::backend-docbook[]
endif::doctype-manpage[]
-ENVIRONMENT VARIABLES
----------------------
+== ENVIRONMENT VARIABLES
+
include::common-lib-env.txt[]
-include::common-ppp-env.txt[]
-CLI
-~~~
-`BABELTRACE_CLI_LOG_LEVEL`::
- `babeltrace2` CLI's log level. The available values are the same as
- for the manopt:babeltrace2(1):--log-level option.
+=== CLI
+
+`BABELTRACE_CLI_LOG_LEVEL`='LVL'::
+ Force `babeltrace2` CLI's log level to be 'LVL'.
++
+If this environment variable is set, it overrides the log level set by
+the manopt:babeltrace2(1):--log-level option for the CLI logger.
++
+The available values for 'LVL' are:
++
+--
+include::common-log-levels.txt[]
+--
-`BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH`::
- Set to `0` to disable the warning message which `babeltrace2` prints
+`BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH`=`0`::
+ Disable the warning message which man:babeltrace2-convert(1) prints
when you convert a trace with a relative path that's also the name
of a `babeltrace2` command.
+
+`BABELTRACE_DEBUG`=`1`::
+ Legacy variable: equivalent to setting the nlopt:--log-level option
+ to `TRACE`.
+
+`BABELTRACE_VERBOSE`=`1`::
+ Legacy variable: equivalent to setting the nlopt:--log-level option
+ to `INFO`.
-FILES
------
+== FILES
+
`$HOME/.local/lib/babeltrace2/plugins`::
User plugin directory.
+{system_plugin_path}+::
System plugin directory.
+
++{system_plugin_provider_path}+::
+ System plugin provider directory.
-EXIT STATUS
------------
+== EXIT STATUS
+
*0* on success, *1* otherwise.
-Command information
-~~~~~~~~~~~~~~~~~~~
-opt:-h, opt:--help::
+=== Command information
+
+opt:-h::
+opt:--help::
Show the command's help and quit.
-[[params-fmt]]
-Parameters format
-~~~~~~~~~~~~~~~~~
-The format of the 'PARAMS' option's argument is a comma-separated
-list of `NAME=VALUE` assignments:
+The format of 'PARAMS' is a comma-separated list of 'NAME'='VALUE'
+assignments:
[verse]
'NAME'='VALUE'[,'NAME'='VALUE']...
'NAME'::
- Parameter name (C{nbsp}identifier plus the `:`, `.`, and `-` characters).
+ Parameter name (C~identifier plus the `:`, `.`, and `-`
+ characters).
'VALUE'::
One of:
* Double-quoted string (accepts escape characters).
-* Array, formatted as an opening `[`, a list of comma-separated values
- (as described by the current list) and a closing `]`.
+* Array, formatted as an opening `[`, a comma-separated list of 'VALUE',
+ and a closing `]`.
-You may put whitespaces around the individual `=` (assignment) and `,`
-(separator) characters.
+* Map, formatted as an opening `{`, a comma-separated list of
+ 'NAME'='VALUE' assignments, and a closing `}`.
+
+You may put whitespaces around the individual `=` (assignment), `,`
+(separator), `[` (array beginning), `]` (array end), `{` (map
+beginning), and `}` (map end) characters.
--
Example:
+[role="term"]
----
-babeltrace2 ... --params='many=null, fresh=yes, condition=false,
- squirrel=-782329, play=+23, observe=3.14,
- simple=beef, needs-quotes="some string",
- escape.chars-are:allowed="a \" quote",
- things=[1, "2", 3]'
+--params='many=null, fresh=yes, condition=false, squirrel=-782329,
+ play=+23, observe=3.14, simple=beef,
+ needs-quotes="some string",
+ escape.chars-are:allowed="a \" quote",
+ things=[1, "hello", 2.71828],
+ frog={slow=2, bath=[bike, 23], blind=NO}'
----
IMPORTANT: Like in the example above, make sure to single-quote the
-whole argument when you run this command from a shell.
+whole argument when you run this command from a shell, as it can contain
+many special characters.
+++ /dev/null
-Plugin path
-~~~~~~~~~~~
-This command loads Babeltrace plugins to perform its operation. The
-search path for Babeltrace plugins is, in this order:
-
-. The colon-separated list of directories in the
- `BABELTRACE_PLUGIN_PATH` environment variable.
-
-. The colon-separated list of directories in the opt:--plugin-path
- option.
-
-. *If the opt:--omit-home-plugin-path option is absent*:
- `$HOME/.local/lib/babeltrace2/plugins`
-
-. *If the opt:--omit-system-plugin-path option is absent*:
- +{system_plugin_path}+
-
-You can use the man:babeltrace2-list-plugins(1) command to dynamically
-list the available plugins.
+++ /dev/null
-`BABELTRACE_COMMON_LOG_LEVEL`::
- Common functions's log level. The available values are the same as
- for the manopt:babeltrace2(1):--log-level option of man:babeltrace2(1).
-
-`BABELTRACE_COMPAT_LOG_LEVEL`::
- Compatibility functions's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
-
-`BABELTRACE_TERM_COLOR`::
- Force the terminal color support. The available values are:
-+
---
-`AUTO`::
- 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.
-
-`ALWAYS`::
- Always emit terminal color codes.
---
--- /dev/null
+`BABELTRACE_TERM_COLOR`=(`AUTO` | `NEVER` | `ALWAYS`)::
+ Force the terminal color support for the man:babeltrace2(1) program
+ and the project's plugins.
++
+The available values are:
++
+--
+`AUTO`::
+ 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.
+
+`ALWAYS`::
+ Always emit terminal color codes.
+--
--- /dev/null
+.Pretty-print the events, in order, of one or more CTF traces.
+====
+[role="term"]
+----
+$ babeltrace2 my-ctf-traces
+----
+
+[role="term"]
+----
+$ babeltrace2 my-ctf-traces
+----
+
+[role="term"]
+----
+$ babeltrace2 my-ctf-trace-1 my-ctf-trace-2 my-ctf-trace-3
+----
+====
+
+.Trim a CTF trace and pretty-print the events.
+====
+[role="term"]
+----
+$ babeltrace2 my-ctf-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 write a CTF trace.
+====
+[role="term"]
+----
+$ babeltrace2 my-ctf-trace --stream-intersection \
+ --timerange=22:55:43,22:55:46.967687564 \
+ --output-format=ctf --output=out-ctf-trace
+----
+====
+
+.Print the available remote LTTng sessions (through LTTng live).
+====
+[role="term"]
+----
+$ babeltrace2 --input-format=lttng-live net://localhost
+----
+====
+
+.Pretty-print LTTng live events.
+====
+[role="term"]
+----
+$ babeltrace2 net://localhost/host/myhostname/my-session-name
+----
+====
+
+.Record LTTng live traces to the file system (as CTF traces).
+====
+[role="term"]
+----
+$ babeltrace2 net://localhost/host/myhostname/my-session-name \
+ --params=session-not-found-action=end \
+ --output-format=ctf --output=out-ctf-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 ctf-trace1 ctf-trace2 ctf-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 the Unix epoch.
+====
+[role="term"]
+----
+$ babeltrace2 ctf-trace --component=src.my-plugin.my-src \
+ --params='path="spec-trace",output-some-event-type=yes' \
+ --clock-seconds
+----
+====
+
+.Send LTTng live events to an explicit sink component.
+====
+[role="term"]
+----
+$ babeltrace2 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/ctf/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-ctf-trace
+----
+====
+
+.Print the metadata text of a CTF trace.
+====
+[role="term"]
+----
+$ babeltrace2 /path/to/ctf/trace --output-format=ctf-metadata
+----
+====
+++ /dev/null
-`ctf` plugin
-~~~~~~~~~~~~
-`BABELTRACE_PLUGIN_CTF_BTR_LOG_LEVEL`::
- Binary type reader's log level. The available values are the same as
- for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
-
-`BABELTRACE_PLUGIN_CTF_METADATA_LOG_LEVEL`::
- Metadata decoder's log level. The available values are the same as
- for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
-
-`BABELTRACE_PLUGIN_CTF_NOTIF_ITER_LOG_LEVEL`::
- Notification iterator's log level. The available values are the same
- as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
-BUGS
-----
+== BUGS
+
If you encounter any issue or usability problem, please report it on the
https://bugs.linuxfoundation.org/buglist.cgi?product=Diamon&component=Babeltrace[Babeltrace
bug tracker].
-RESOURCES
----------
+== RESOURCES
+
The Babeltrace project shares some communication channels with the
-http://lttng.org/[LTTng project].
+https://lttng.org/[LTTng project].
-* http://diamon.org/babeltrace[Babeltrace website]
-* http://git.linuxfoundation.org/?p=diamon/babeltrace.git[Git repository]
-* http://github.com/efficios/[EfficiOS GitHub organization]
-* https://ci.lttng.org/job/babeltrace_master_build/[Continuous integration]
-* http://lists.lttng.org[Mailing list] for support and
+* https://diamon.org/babeltrace[Babeltrace website]
+* https://lists.lttng.org[Mailing list] for support and
development: `lttng-dev@lists.lttng.org`
-* irc://irc.oftc.net/lttng[IRC channel]: `#lttng` on `irc.oftc.net`
+* irc://irc.oftc.net/lttng[IRC channel]: `#bt2` or `#lttng` on
+ `irc.oftc.net`
+* http://git.linuxfoundation.org/?p=diamon/babeltrace.git[Git repository]
+* https://github.com/efficios/babeltrace[GitHub project]
+* https://ci.lttng.org/view/Babeltrace/[Continuous integration]
+* https://review.lttng.org/q/project:babeltrace[Code review]
+
+== AUTHORS
-AUTHORS
--------
-The Babeltrace project is the result of efforts by many regular
+The Babeltrace~2 project is the result of hard work by many regular
developers and occasional contributors.
The current project maintainer is
mailto:jeremie.galarneau@efficios.com[Jérémie Galarneau].
-COPYRIGHT
----------
-This {manpagetype} is part of the Babeltrace project.
+== COPYRIGHT
+
+This {manpagetype} is part of the Babeltrace~2 project.
Babeltrace is distributed under the
https://opensource.org/licenses/MIT[MIT license].
-General options
-~~~~~~~~~~~~~~~
+[[gen-opts]]
+=== General
+
+You can use those options before the command name.
+
See man:babeltrace2(1) for more details.
-nlopt:-d, nlopt:--debug::
- Turn the debugging mode on.
+nlopt:-d::
+nlopt:--debug::
+ Legacy option: this is equivalent to nlopt:--log-level=`TRACE`.
+nlopt:-l 'LVL'::
nlopt:--log-level='LVL'::
- Set the log level of all known Babeltrace loggers to 'LVL'.
+ Set the log level of all known Babeltrace~2 loggers to 'LVL'.
+
+nlopt:--omit-home-plugin-path::
+ Do not search for plugins in `$HOME/.local/lib/babeltrace2/plugins`.
-nlopt:-v, nlopt:--verbose::
- Turn the verbose mode on.
+nlopt:--omit-system-plugin-path::
+ Do not search for plugins in +{system_plugin_path}+.
-nlopt:-h, nlopt:--help::
- Show general help and quit.
+nlopt:--plugin-path='PATH'[:__PATH__]...::
+ Add 'PATH' to the list of paths in which plugins can be found.
-nlopt:-V, nlopt:--version::
- Show version and quit.
+nlopt:-v::
+nlopt:--verbose::
+ Legacy option: this is equivalent to nlopt:--log-level=`INFO`.
-Babeltrace library
-~~~~~~~~~~~~~~~~~~
-include::common-common-compat-env.txt[]
-
-`BABELTRACE_DISABLE_PYTHON_PLUGINS`::
- Set to `1` to disable the loading of any Babeltrace Python plugin.
-
-`BABELTRACE_LOGGING_GLOBAL_LEVEL`::
- Babeltrace library's global log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1)
-
-`BABELTRACE_NO_DLCLOSE`::
- Set to `1` to make the Babeltrace library leave any dynamically
- loaded modules (plugins and Python plugin provider) open at exit.
- This can be useful for debugging purposes.
-
-`BABELTRACE_PLUGIN_PATH`::
- Colon-separated list of directories, in order, in which dynamic
- plugins can be found before other directories are considered.
+=== Babeltrace~2 library
+
+include::common-common-env.txt[]
+
+`BABELTRACE_PLUGIN_PATH`='PATHS'::
+ Set the list of directories, in order, in which dynamic plugins can
+ be found before other directories are considered to 'PATHS'
+ (colon-separated, or semicolon on Windows).
+
+`LIBBABELTRACE2_DISABLE_PYTHON_PLUGINS`=`1`::
+ Disable the loading of any Babeltrace~2 Python plugin.
+
+`LIBBABELTRACE2_INIT_LOG_LEVEL`='LVL'::
+ Force the Babeltrace~2 library's initial log level to be 'LVL'.
++
+If this environment variable is set, it overrides the log level set by
+the manopt:babeltrace2(1):--log-level option for the Babeltrace~2
+library logger.
++
+The available values for 'LVL' are:
++
+--
+include::common-log-levels.txt[]
+--
+
+`LIBBABELTRACE2_NO_DLCLOSE`=`1`::
+ Make the Babeltrace~2 library leave any dynamically loaded
+ modules (plugins and plugin providers) open at exit. This can be
+ useful for debugging purposes.
+
+`LIBBABELTRACE2_PLUGIN_PROVIDER_DIR`='DIR'::
+ Set the directory from which the Babeltrace~2 library
+ dynamically loads plugin provider shared objects to 'DIR'.
++
+If this environment variable is set, it overrides the default plugin
+provider directory.
+
+
+=== Babeltrace~2 Python bindings
+
+`BABELTRACE_PYTHON_BT2_LOG_LEVEL`='LVL'::
+ Force the Babeltrace~2 Python bindings log level to be 'LVL'.
++
+If this environment variable is set, it overrides the log level set by
+the manopt:babeltrace2(1):--log-level option for the Python bindings
+logger.
++
+The available values for 'LVL' are:
++
+--
+include::common-log-levels.txt[]
+--
--- /dev/null
+`NONE`::
+`N`::
+ Logging is disabled.
+
+`FATAL`::
+`F`::
+ Severe errors that lead the execution to abort immediately.
++
+This level should be enabled in production.
+
+`ERROR`::
+`E`::
+ Errors that might still allow the execution to continue.
++
+Usually, once one or more errors are reported at this level, the
+application, plugin, or library won't perform any more useful task, but
+it should still exit cleanly.
++
+This level should be enabled in production.
+
+`WARN`::
+`WARNING`::
+`W`::
+ Unexpected situations which still allow the execution to continue.
++
+This level should be enabled in production.
+
+`INFO`::
+`I`::
+ Informational messages that highlight progress or important states
+ of the application, plugins, or library.
++
+This level can be enabled in production.
+
+`DEBUG`::
+`D`::
+ Debugging information, with a higher level of details than the
+ `TRACE` level.
++
+This level should :not: be enabled in production.
+
+`TRACE`::
+`T`::
+ Low-level debugging context information.
++
+This level should :not: be enabled in production.
+++ /dev/null
-Plugin path
-~~~~~~~~~~~
-opt:--omit-home-plugin-path::
- Do not search for plugins in `$HOME/.local/lib/babeltrace2/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.
+++ /dev/null
-Python plugin provider
-~~~~~~~~~~~~~~~~~~~~~~
-`BABELTRACE_PYTHON_PLUGIN_PROVIDER_LOG_LEVEL`::
- Python plugin provider's log level. The available values are the
- same as for the manopt:babeltrace2(1):--log-level option of
- man:babeltrace2(1).
--- /dev/null
+See man:babeltrace2-intro(7) to learn more about the Babeltrace~2
+project and its core concepts.
--- /dev/null
+[verse]
+__YYYY__-__MM__-__DD__ __HH__:__II__[:__SS__[.__NANO__]]
+__HH__:__II__[:__SS__[.__NANO__]]
+$$[$$-]__SEC__[.__NANO__]
+
+'YYYY'::
+ 4-digit year.
+
+'MM'::
+ 2-digit month (January is `01`).
+
+'DD'::
+ 2-digit day.
+
+'HH'::
+ 2-digit hour (24-hour format).
+
+'II'::
+ 2-digit minute.
+
+'SS'::
+ 2-digit second.
+
+'NANO'::
+ Nanoseconds (up to nine digits).
+
+'SEC'::
+ Seconds since origin.
projects / babeltrace.git / commitdiff
