From e70712b34fcae860414660c6b10451f57b50c25d Mon Sep 17 00:00:00 2001 From: Philippe Proulx Date: Mon, 12 Aug 2019 11:21:43 -0400 Subject: [PATCH] Update manual pages for 2.0.0-rc1 Signed-off-by: Philippe Proulx Change-Id: I81b1a12efc1cfdb34084896d3fd4a4b05996530b Reviewed-on: https://review.lttng.org/c/babeltrace/+/2046 Reviewed-by: Francis Deslauriers --- doc/man/Makefile.am | 15 +- doc/man/README.adoc | 208 ++-- doc/man/asciidoc-attrs.conf.in | 2 + doc/man/babeltrace2-convert.1.txt | 893 ++++++++---------- ...trace2-filter.lttng-utils.debug-info.7.txt | 242 ++--- doc/man/babeltrace2-filter.utils.muxer.7.txt | 118 ++- .../babeltrace2-filter.utils.trimmer.7.txt | 164 ++-- doc/man/babeltrace2-help.1.txt | 76 +- doc/man/babeltrace2-intro.7.txt | 387 ++++---- doc/man/babeltrace2-list-plugins.1.txt | 46 +- doc/man/babeltrace2-plugin-ctf.7.txt | 52 +- doc/man/babeltrace2-plugin-lttng-utils.7.txt | 37 +- doc/man/babeltrace2-plugin-text.7.txt | 57 +- doc/man/babeltrace2-plugin-utils.7.txt | 58 +- ...trace2-query-babeltrace.support-info.7.txt | 148 +++ ...ltrace2-query-babeltrace.trace-infos.7.txt | 113 +++ doc/man/babeltrace2-query.1.txt | 96 +- doc/man/babeltrace2-run.1.txt | 322 ++++--- doc/man/babeltrace2-sink.ctf.fs.7.txt | 278 ++++-- doc/man/babeltrace2-sink.text.details.7.txt | 173 ++++ doc/man/babeltrace2-sink.text.pretty.7.txt | 136 +-- doc/man/babeltrace2-sink.utils.counter.7.txt | 112 +-- doc/man/babeltrace2-sink.utils.dummy.7.txt | 76 +- doc/man/babeltrace2-source.ctf.fs.7.txt | 373 ++++---- .../babeltrace2-source.ctf.lttng-live.7.txt | 246 ++--- doc/man/babeltrace2-source.text.dmesg.7.txt | 111 ++- doc/man/babeltrace2.1.txt | 237 +++-- doc/man/bt-asciidoc.conf | 103 +- doc/man/common-cli-env.txt | 35 +- doc/man/common-cli-files.txt | 7 +- doc/man/common-cmd-footer.txt | 4 +- doc/man/common-cmd-info-options.txt | 7 +- doc/man/common-cmd-params-format.txt | 37 +- doc/man/common-cmd-plugin-path.txt | 19 - doc/man/common-common-compat-env.txt | 23 - doc/man/common-common-env.txt | 17 + doc/man/common-convert-examples.txt | 132 +++ doc/man/common-ctf-plugin-env.txt | 16 - doc/man/common-footer.txt | 36 +- doc/man/common-gen-options.txt | 31 +- doc/man/common-lib-env.txt | 72 +- doc/man/common-log-levels.txt | 46 + doc/man/common-plugin-path-options.txt | 11 - doc/man/common-ppp-env.txt | 6 - doc/man/common-see-babeltrace2-intro.txt | 2 + doc/man/common-trimmer-time-format.txt | 28 + 46 files changed, 3156 insertions(+), 2252 deletions(-) create mode 100644 doc/man/babeltrace2-query-babeltrace.support-info.7.txt create mode 100644 doc/man/babeltrace2-query-babeltrace.trace-infos.7.txt create mode 100644 doc/man/babeltrace2-sink.text.details.7.txt delete mode 100644 doc/man/common-cmd-plugin-path.txt delete mode 100644 doc/man/common-common-compat-env.txt create mode 100644 doc/man/common-common-env.txt create mode 100644 doc/man/common-convert-examples.txt delete mode 100644 doc/man/common-ctf-plugin-env.txt create mode 100644 doc/man/common-log-levels.txt delete mode 100644 doc/man/common-plugin-path-options.txt delete mode 100644 doc/man/common-ppp-env.txt create mode 100644 doc/man/common-see-babeltrace2-intro.txt create mode 100644 doc/man/common-trimmer-time-format.txt diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 850fdf04..c4a42d1e 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -21,11 +21,14 @@ MAN7_NAMES = babeltrace2-filter.utils.muxer \ 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 = @@ -48,14 +51,14 @@ COMMON_TXT = \ $(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 diff --git a/doc/man/README.adoc b/doc/man/README.adoc index 1ebb48b0..f1e650e8 100644 --- a/doc/man/README.adoc +++ b/doc/man/README.adoc @@ -1,11 +1,15 @@ -= 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). @@ -13,114 +17,158 @@ 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 @@ -128,6 +176,30 @@ configuration-dependent attributes which you can use anywhere in the 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 <>), +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 diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in index ae414315..ad1183f1 100644 --- a/doc/man/asciidoc-attrs.conf.in +++ b/doc/man/asciidoc-attrs.conf.in @@ -1,5 +1,7 @@ [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 diff --git a/doc/man/babeltrace2-convert.1.txt b/doc/man/babeltrace2-convert.1.txt index 62c5172a..d20862a9 100644 --- a/doc/man/babeltrace2-convert.1.txt +++ b/doc/man/babeltrace2-convert.1.txt @@ -1,57 +1,61 @@ -babeltrace2-convert(1) -===================== += babeltrace2-convert(1) :manpagetype: command -: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* [<>] [*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* [<>] [*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* [<>] [*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* [<>] [*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* [<>] [*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"] ---- @@ -63,52 +67,69 @@ If you need to make sure that you are executing the `convert` command, 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 <> to learn -how to enable them. +optional. See <> 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 -<>). You can also use one -of the many specific `convert` command options and arguments to create -implicit components from known component classes (see -<>). For example, you can -specify a single path argument to print the merged events of a CTF trace -on the console: +<>). You can also use +one of the many specific `convert` command options (see +<>) +and non-option arguments (see <>) 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. @@ -117,33 +138,44 @@ This is the equivalent of creating and connecting together: 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"] ---- @@ -156,17 +188,16 @@ character instead of a space. This is useful if the resulting arguments are not the direct input of a shell, for example if passed to `xargs -0`. -See <> for usage examples. +See <> 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. @@ -182,82 +213,101 @@ multiple times as different component instances. Immediately following a opt:--component option on the command line, the created component is known as the _current component_ (until the next -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 <> for the format of 'PARAMS'. +If 'PARAMS' contains a key which exists in the current component's +initialization parameters, replace the parameter. -See <> for usage examples. +See <> 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. + @@ -287,13 +337,13 @@ Examples: + [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"] @@ -302,24 +352,23 @@ $ babeltrace2 /path/to/trace --debug-info-full-path ---- * To create an implicit compcls:sink.text.pretty component - (pretty-printing text output to the console or to a file), do any of: + (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, <> 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: + @@ -335,17 +384,11 @@ $ babeltrace2 /path/to/trace --no-delta + [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: + @@ -356,26 +399,24 @@ $ babeltrace2 /path/to/trace --output-format=dummy * To create an implicit compcls:sink.ctf.fs component (CTF traces written to the file system), specify the opt:--output-format=`ctf` - 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 @@ -383,76 +424,44 @@ is: [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 <> 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 <> 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 <> to learn how to -use the following options. +=== Explicit component creation + +See <> 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`:: @@ -467,103 +476,137 @@ The available values for 'TYPE' are: 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 <> and +<> 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 <> 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 + <>), 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 <>. + 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 <>. + -See man:babeltrace2-sink.text.pretty(7) to learn more about -this component class. +See <>. ++ +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 @@ -574,7 +617,7 @@ You can combine this option with opt:--clock-offset-ns. opt:--clock-offset-ns='NS':: Set the manparam:source.ctf.fs:clock-class-offset-ns initialization - 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 @@ -584,44 +627,53 @@ that the component creates. 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 <> 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 @@ -655,10 +707,9 @@ debugging information. [[impl-opts-text]] === Implicit compcls:sink.text.pretty component -If you specify at least one of the following options, you create an -implicit compcls:sink.text.pretty component. The `convert` command also -creates a default implicit compcls:sink.text.pretty component if no -other sink component exists. +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. @@ -689,7 +740,7 @@ opt:--clock-seconds:: 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 @@ -699,9 +750,8 @@ The available values for 'WHEN' are: + -- `auto`:: - Automatic color support depending on the capabilities of the - terminal(s) to which the standard output and error streams are - connected. + 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. @@ -756,229 +806,118 @@ When the manparam:sink.text.pretty:no-delta parameter is true, the component does not print the duration since the last event on the line. -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, <> and -<>, 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) diff --git a/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt index ca05d708..090d07bd 100644 --- a/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt +++ b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt @@ -1,101 +1,115 @@ -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 +<>) 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 (<>), 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 (<>). +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 <>), 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 <>). 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 @@ -151,20 +165,20 @@ $ LD_PRELOAD=liblttng-ust-dl.so my-app -- -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: @@ -175,9 +189,10 @@ 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. @@ -185,11 +200,11 @@ NOTE: It is currently not possible to make this component search for 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 @@ -197,71 +212,62 @@ is, the root of the target file system. 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) diff --git a/doc/man/babeltrace2-filter.utils.muxer.7.txt b/doc/man/babeltrace2-filter.utils.muxer.7.txt index dde289a1..67fe11e5 100644 --- a/doc/man/babeltrace2-filter.utils.muxer.7.txt +++ b/doc/man/babeltrace2-filter.utils.muxer.7.txt @@ -1,86 +1,82 @@ -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) diff --git a/doc/man/babeltrace2-filter.utils.trimmer.7.txt b/doc/man/babeltrace2-filter.utils.trimmer.7.txt index cf49d9c5..b1f754e5 100644 --- a/doc/man/babeltrace2-filter.utils.trimmer.7.txt +++ b/doc/man/babeltrace2-filter.utils.trimmer.7.txt @@ -1,125 +1,111 @@ -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 <> 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 <> 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) diff --git a/doc/man/babeltrace2-help.1.txt b/doc/man/babeltrace2-help.1.txt index e1b7d7c5..37216337 100644 --- a/doc/man/babeltrace2-help.1.txt +++ b/doc/man/babeltrace2-help.1.txt @@ -1,65 +1,67 @@ -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* [<>] *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* [<>] *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 <> for usage examples. - +See <> 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 ---- ==== @@ -67,7 +69,7 @@ $ babeltrace2 help my-plugin ==== [role="term"] ---- -$ babeltrace2 help src.my-plugin.my-source +$ babeltrace2 help source.ctf.fs ---- ==== @@ -75,20 +77,22 @@ $ babeltrace2 help src.my-plugin.my-source ==== [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) diff --git a/doc/man/babeltrace2-intro.7.txt b/doc/man/babeltrace2-intro.7.txt index 62cea708..47754e0a 100644 --- a/doc/man/babeltrace2-intro.7.txt +++ b/doc/man/babeltrace2-intro.7.txt @@ -1,158 +1,163 @@ -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 <> section lists the parts of the -project and shows the major changes from Babeltrace{nbsp}1 to -Babeltrace{nbsp}2 while the <> section -defines the core concepts of Babeltrace. +The <> section describes the +parts of the project and shows the major changes from Babeltrace~1 +to Babeltrace~2 while the <> section defines the core concepts of Babeltrace~2. -The <> section shows -how some <> are visually represented in other -Babeltrace man pages. +The <> section +shows how some <> 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 <> -and <>, build and run <>, and more (see the <> section for -more details about those concepts). All the other Babeltrace parts rely -on this library. +and <>, build and run <>, and more (see the <> 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 <>, connect + their <> 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 +<> 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 <> shipped with the project. +Babeltrace~2 project's plugins:: + The Babeltrace~2 <> 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 <> 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 <> 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 <> 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 <> 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 <> 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 <> and its <>, but also as command-line actions and options in the -<>. The other Babeltrace man pages -assume that you are familiar with the following definitions. +<>. 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 - <> instances. + A reusable class which you can instantiate as one or more + <> within a <>. + -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 <>. @@ -161,26 +166,25 @@ There are three types of components: + -- Source component:: - An input component which produces <>. + An input component which produces <>. + -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 <>. 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 <> 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 <>, from which are sent or - to which are received <> when the <> is running. + where are received <> when the <> 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 <>. + -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 <> is configured (the first time it runs), you +cannot connect ports for the remaining graph's lifetime. [[conn]]Connection:: The link between an output <> and an input port through - which <> flow when a <> is running. + which <> flow when a <> runs. + +[[msg-iter]]Message iterator:: + An iterator on an input <> of which the returned elements + are <>. ++ +A <> or another message iterator can create many message +iterators on a single input port, before or while the <> runs. -[[notif]]Notification:: - An atomic element sent from an output <> to an - input port. +[[msg]]Message:: + The element of a <>. ++ +Messages flow from output <> to input ports. + -A source <> produces notifications, while a sink -component consumes them. A filter component can both consume and -produce notifications. +A source <> <> 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. @@ -246,10 +263,10 @@ Packet end:: 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. @@ -265,61 +282,65 @@ Discarded packets:: [[graph]]Trace processing graph:: A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where - nodes are <> and <> flow from + nodes are <> and <> flow from output <> to input ports. + You can build a trace processing graph with -<>, with the <>, or with the man:babeltrace2-run(1) and -man:babeltrace2-convert(1) commands. +<>, with the +<>, 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 +<> work one message at a time to perform the +trace conversion or analysis duty. [[plugin]]Plugin:: - A container of <> as a shared library. + A container, or package, of <> 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. + -<> 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 <> as a <>. +<> 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 +<> as a <>. + -The <> uses the -'TYPE.PLUGIN.COMPCLS' format to identify a specific component -class within a specific plugin. 'TYPE' is either `source`, `filter`, -or `sink`. +The <> 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 - <>, possibly with the help of query - parameters. + <>, 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 <>, the +<>, 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 <> type, <> name, -and component class name at the top. Just below, between square -brackets, is its component instance name within the <> type, +<> name, and component class name at the top. Just below, +between square brackets, is its component name within the <>. Each <> 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: @@ -334,9 +355,9 @@ 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 <> are arrows from output @@ -356,28 +377,28 @@ For example, here's a simple conversion graph: +-----------------+ ---- -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 @@ -410,6 +431,6 @@ stream using some criteria: include::common-footer.txt[] -SEE ALSO --------- +== SEE ALSO + man:babeltrace2(1) diff --git a/doc/man/babeltrace2-list-plugins.1.txt b/doc/man/babeltrace2-list-plugins.1.txt index 6c15e079..e4e452b3 100644 --- a/doc/man/babeltrace2-list-plugins.1.txt +++ b/doc/man/babeltrace2-list-plugins.1.txt @@ -1,51 +1,45 @@ -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* [<>] *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) diff --git a/doc/man/babeltrace2-plugin-ctf.7.txt b/doc/man/babeltrace2-plugin-ctf.7.txt index 9cc93ed9..b65cf04c 100644 --- a/doc/man/babeltrace2-plugin-ctf.7.txt +++ b/doc/man/babeltrace2-plugin-ctf.7.txt @@ -1,49 +1,49 @@ -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) diff --git a/doc/man/babeltrace2-plugin-lttng-utils.7.txt b/doc/man/babeltrace2-plugin-lttng-utils.7.txt index c80b1040..66272d5a 100644 --- a/doc/man/babeltrace2-plugin-lttng-utils.7.txt +++ b/doc/man/babeltrace2-plugin-lttng-utils.7.txt @@ -1,30 +1,27 @@ -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). @@ -32,7 +29,7 @@ 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) diff --git a/doc/man/babeltrace2-plugin-text.7.txt b/doc/man/babeltrace2-plugin-text.7.txt index f88db0b4..5dc680ca 100644 --- a/doc/man/babeltrace2-plugin-text.7.txt +++ b/doc/man/babeltrace2-plugin-text.7.txt @@ -1,44 +1,51 @@ -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) diff --git a/doc/man/babeltrace2-plugin-utils.7.txt b/doc/man/babeltrace2-plugin-utils.7.txt index 49efecbf..8019476b 100644 --- a/doc/man/babeltrace2-plugin-utils.7.txt +++ b/doc/man/babeltrace2-plugin-utils.7.txt @@ -1,58 +1,54 @@ -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), diff --git a/doc/man/babeltrace2-query-babeltrace.support-info.7.txt b/doc/man/babeltrace2-query-babeltrace.support-info.7.txt new file mode 100644 index 00000000..3d43f8e9 --- /dev/null +++ b/doc/man/babeltrace2-query-babeltrace.support-info.7.txt @@ -0,0 +1,148 @@ += 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 +<>. + + +== 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) diff --git a/doc/man/babeltrace2-query-babeltrace.trace-infos.7.txt b/doc/man/babeltrace2-query-babeltrace.trace-infos.7.txt new file mode 100644 index 00000000..a48d8c14 --- /dev/null +++ b/doc/man/babeltrace2-query-babeltrace.trace-infos.7.txt @@ -0,0 +1,113 @@ += 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 + +A trace info map contains: + +nlqres:stream-infos='STREAM-INFOS' vtype:[array of stream info maps]:: + Stream info maps (see <>) 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) diff --git a/doc/man/babeltrace2-query.1.txt b/doc/man/babeltrace2-query.1.txt index 11a78dc0..c9e13456 100644 --- a/doc/man/babeltrace2-query.1.txt +++ b/doc/man/babeltrace2-query.1.txt @@ -1,33 +1,29 @@ -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* [<>] *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`:: @@ -41,67 +37,63 @@ The available values for 'TYPE' are: 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 <> -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 <> for usage examples. - - -include::common-cmd-params-format.txt[] +See <> 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 <> 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"' ---- ==== @@ -117,12 +109,14 @@ $ babeltrace2 query sink.my-plugin.my-sink some-object 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) diff --git a/doc/man/babeltrace2-run.1.txt b/doc/man/babeltrace2-run.1.txt index dcdd26b8..4c376b78 100644 --- a/doc/man/babeltrace2-run.1.txt +++ b/doc/man/babeltrace2-run.1.txt @@ -1,45 +1,44 @@ -babeltrace2-run(1) -================= += babeltrace2-run(1) :manpagetype: command -:revdate: 5 October 2017 +:revdate: 14 September 2019 -NAME ----- -babeltrace2-run - Create a trace processing graph and run it +== NAME + +babeltrace2-run - Create a Babeltrace 2 trace processing graph and run it -SYNOPSIS --------- +[[synopsis]] +== SYNOPSIS + [verse] -*babeltrace2 run* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path] - [opt:--omit-system-plugin-path] - [opt:--plugin-path='PATH'[:__PATH__]...] - [opt:--retry-duration='DURUS'] - opt:--connect='CONN-RULE'... 'COMPONENTS' +*babeltrace2* [<>] *run* [opt:--retry-duration='TIME-US'] + opt:--connect='CONN-RULE'... 'COMPONENTS' + +== DESCRIPTION -DESCRIPTION ------------ -The `run` command creates a trace processing graph and runs it. +The `run` command creates a Babeltrace~2 trace processing graph and +runs it. -See man:babeltrace2-intro(7) to learn more about the Babeltrace -project and its core concepts. +include::common-see-babeltrace2-intro.txt[] -The `run` command uses libbabeltrace2 to dynamically load plugins which +The `run` command dynamically loads Babeltrace~2 plugins which supply component classes. With the `run` command, you specify which -component classes to instantiate as components and how they must be -connected. +component classes to instantiate as components and how to connect them. The steps to write a `babeltrace2 run` command line are: -. Specify which component classes to instantiate as components and - how. This is the 'COMPONENTS' part of the synopsis. See - <> to learn more. +. Specify which component classes to instantiate as components with many + opt:--component options and how to configure them. ++ +This is the 'COMPONENTS' part of the <>. See +<> to learn more. -. Specify how to connect component instances together with one or more - opt:--connect options. See <> to - learn more. +. Specify how to connect components together with one or more + opt:--connect options. ++ +See <> to learn more. NOTE: The man:babeltrace2-convert(1) command is a specialization of the `run` command for the very common case of converting one or more traces: @@ -50,13 +49,13 @@ equivalent `run` command line instead. [[create-comps]] -Create components -~~~~~~~~~~~~~~~~~ +=== Create components + To create a component, use the opt:--component option. This option specifies: -* **Optional**: The name of the component instance. You can also use the - opt:--name option for this. +* The name of the component, unique amongst all the component names of + the trace processing graph. * The type of the component class to instantiate: source, filter, or sink. @@ -66,9 +65,9 @@ specifies: * The name of the component class to instantiate. -You can use the opt:--component option multiple times to create -multiple components. You can instantiate the same component class -multiple times as different component instances. +Use the opt:--component option multiple times to create multiple +components. You can instantiate the same component class multiple times +as different components. At any point in the command line, the opt:--base-params sets the current base initialization parameters and the opt:--reset-base-params resets @@ -80,66 +79,58 @@ Immediately following a opt:--component option on the command line, the created component is known as the _current component_ (until the next opt:--component option). -The following, optional command-line options apply to the current -component: - -opt:--name='NAME':: - Set the name of the current component to 'NAME'. - -opt:--params='PARAMS':: - Add 'PARAMS' to the initialization parameters of the current - component. If 'PARAMS' contains a key which exists in the current - component's initialization parameters, this parameter is replaced. -+ -See <> for the format of 'PARAMS'. +The opt:--params='PARAMS' option adds parameters to the current +component's initialization parameters. If 'PARAMS' contains a key which +exists in the current component's initialization parameters, this +parameter is replaced. [[connect-comps]] -Connect components -~~~~~~~~~~~~~~~~~~ +=== Connect components + The components which you create from component classes with the -opt:--component option (see <>) can -create input and output _ports_ depending on their type. An output port -is where notifications, like trace events, are sent. An input port is -where notifications are received. For a given component instance, each -port has a unique name. +opt:--component option (see <>) add +input and output _ports_ depending on their type. An output port is from +where messages, like trace events, are sent. An input port is where +messages are received. For a given component, each port has a unique +name. The purpose of the `run` command is to create a trace processing graph, that is, to know which component ports to connect together. The command achieves this with the help of the connection rules that you provide -with the opt:--connect option. +with one or more opt:--connect='CONN-RULE' options. -The format of a connection rule (the argument of the opt:--connect -option) is: +The format of 'CONN-RULE' is: [verse] __UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] -'UP-COMP-PATH':: +'UP-COMP-PAT':: Upstream component name pattern. 'UP-PORT-PAT':: - Upstream port name pattern. + Upstream (output) port name pattern. -'DOWN-COMP-PATH':: +'DOWN-COMP-PAT':: Downstream component name pattern. 'DOWN-PORT-PAT':: - Downstream port name pattern. + Downstream (input) port name pattern. When a source or filter component adds a new output port within the processing graph, the `run` command does the following to find an input port to connect it to: ---- -For each connection rule: - If the output port's component's name matches UP-COMP-PAT and - the output port's name matches UP-PORT-PAT: - For each component COMP in the processing graph: +For each connection rule (--connect options, in order): + If the output port's component's name matches UP-COMP-PAT and the + output port's name matches UP-PORT-PAT: + For each component COMP in the trace processing graph: If the name of COMP matches DOWN-COMP-PAT: - Select the first input port of COMP of which the name - matches DOWN-PORT-PAT, or fail with no match. -Fail with no match. + Select the first input port of COMP of which the name matches + DOWN-PORT-PAT, or fail with no match. + +No possible connection: fail with no match. ---- __UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and @@ -151,52 +142,54 @@ When you do not specify __UP-PORT-PAT__ or __DOWN-PORT-PAT__, they are equivalent to `*`. You can leverage this connection mechanism to specify fallbacks with a -careful use of wildcards. For example: +careful use of wildcards, as the order of the opt:--connect options on +the command line is significant. For example: ---- --connect='A.out*:B.in*' --connect=A:B --connect='*:C' ---- -With those connection rules: +With those connection rules, the `run` command connects: * Any output port of which the name starts with `out` of component `A` - is connected to the first input port of which the name starts with - `in` of component `B`. + to the first input port of which the name starts with `in` of + component `B`. -* Any other output port of component `A` is connected to the first - available input port of component `B`. +* Any other output port of component `A` to the first available input + port of component `B`. -* Any other output port (of any component except `A`) is connected to - the first available input port of component `C`. +* Any other output port (of any component except `A`) to the first + available input port of component `C`. The `run` command fails when it cannot find an input port to which to -connect a created output port using the provided connection -rules. +connect a given output port using the provided connection rules. -See <> for more examples. +See <> for more examples. -include::common-cmd-params-format.txt[] +== OPTIONS -include::common-cmd-plugin-path.txt[] +include::common-gen-options.txt[] -OPTIONS -------- -include::common-gen-options.txt[] +=== Component creation +See <> for more details. -Component creation -~~~~~~~~~~~~~~~~~~ -opt:-b 'PARAMS', opt:--base-params='PARAMS':: - Set the current base parameters to 'PARAMS'. You can reset the - current base parameters with the opt:--reset-base-params option. - See <> for the format of 'PARAMS'. +opt:-b 'PARAMS':: +opt:--base-params='PARAMS':: + Set the current base parameters to 'PARAMS'. ++ +You can reset the current base parameters with the +opt:--reset-base-params option. ++ +See the opt:--params option for the format of 'PARAMS'. -opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS':: - Create a component initially named 'NAME' (if specified) from the - component class of type 'TYPE' named 'COMPCLS' found in the plugin - named 'PLUGIN', and set it as the current component. +opt:-c __NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME':: +opt:--component=__NAME__:__COMP-CLS-TYPE__.'PLUGIN-NAME'.'COMP-CLS-NAME':: + Create a component named 'NAME' from the component class of type + 'COMP-CLS-TYPE' named 'COMP-CLS-NAME' found in the plugin named + 'PLUGIN-NAME', and set it as the current component. + The available values for 'TYPE' are: + @@ -217,53 +210,87 @@ The initial initialization parameters of this component are copied from the current base initialization parameters (see the opt:--base-params option). -opt:--name='NAME':: - Set the name of the current component to 'NAME'. The names of all - the components in the processing graph must be unique. +opt:-l 'LVL':: +opt:--log-level='LVL':: + Set the log level of the current component to 'LVL'. ++ +The available values for 'LVL' are: ++ +-- +include::common-log-levels.txt[] +-- -opt:-p 'PARAMS', opt:--params='PARAMS':: +opt:-p 'PARAMS':: +opt:--params='PARAMS':: Add 'PARAMS' to the initialization parameters of the current - component. If 'PARAMS' contains a key which exists in the current - component's initialization parameters, replace the parameter. - See <> for the format of 'PARAMS'. + component. ++ +If 'PARAMS' contains a key which exists in the current component's +initialization parameters, replace the parameter. ++ +-- +include::common-cmd-params-format.txt[] +-- + +opt:-r:: +opt:--reset-base-params:: + Reset the current base parameters. ++ +You can set the current base parameters with the opt:--base-params +option. + -opt:-r, opt:--reset-base-params:: - Reset the current base parameters. You can set the current base - parameters with the opt:--base-params option. +=== Component connection +opt:-x 'CONN-RULE':: +opt:--connect='CONN-RULE':: + Add the connection rule 'CONN-RULE'. ++ +The format of 'CONN-RULE' is: ++ +[verse] +__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__] ++ +-- +'UP-COMP-PAT':: + Upstream component name pattern. + +'UP-PORT-PAT':: + Upstream (output) port name pattern. + +'DOWN-COMP-PAT':: + Downstream component name pattern. + +'DOWN-PORT-PAT':: + Downstream (input) port name pattern. +-- ++ +See <> to learn more. -Component connection -~~~~~~~~~~~~~~~~~~~~ -opt:-x 'CONN-RULE', opt:--connect='CONN-RULE':: - Add the connection rule 'CONN-RULE'. See - <> for the format of 'CONN-RULE'. +=== Graph configuration -Graph configuration -~~~~~~~~~~~~~~~~~~~ -opt:--retry-duration='DURUS':: - Set the duration of a single retry to 'DURUS'{nbsp}µs when a +opt:--retry-duration='TIME-US':: + Set the duration of a single retry to 'TIME-US'~µs when a sink component reports "try again later" (busy network or file system, for example). + -Default: 100000 (100{nbsp}ms). +Default: 100000 (100~ms). -include::common-plugin-path-options.txt[] - include::common-cmd-info-options.txt[] [[examples]] -EXAMPLES --------- +== EXAMPLES + .Create a single-port source component and a single-port sink component and connect them. ==== [role="term"] ---- $ babeltrace2 run --component=A:src.plug.my-src \ - --component=B:sink.plug.my-sink \ - --connect=A:B + --component=B:sink.plug.my-sink \ + --connect=A:B ---- Possible resulting graph: @@ -278,16 +305,6 @@ Possible resulting graph: ---- ==== -.Use the opt:--name option to name the current component. -==== -[role="term"] ----- -$ babeltrace2 run --component=src.plug.my-src --name=the-source \ - --component=the-sink:sink.plug.my-sink \ - --connect=the-source:the-sink ----- -==== - .Use the opt:--params option to set the current component's initialization parameters. ==== In this example, the opt:--params option only applies to component @@ -296,9 +313,9 @@ In this example, the opt:--params option only applies to component [role="term"] ---- $ babeltrace2 run --component=the-source:src.my-plugin.my-src \ - --params='offset=123, flag=true' \ - --component=the-sink:sink.my-plugin.my-sink \ - --connect=the-source:the-sink + --params=offset=123,flag=true \ + --component=the-sink:sink.my-plugin.my-sink \ + --connect=the-source:the-sink ---- ==== @@ -307,20 +324,25 @@ $ babeltrace2 run --component=the-source:src.my-plugin.my-src \ In this example, the effective initialization parameters of the created components are: -* Component `A`: `offset=1203, flag=false` -* Component `B`: `offset=1203, flag=true, type=event` -* Component `C`: `ratio=0.25` +Component `A`:: + `offset=1203, flag=false` + +Component `B`:: + `offset=1203, flag=true, type=event` + +Component `C`:: + `ratio=0.25` [role="term"] ---- -$ babeltrace2 run --base-params='offset=1203, flag=false' \ - --component=A:src.plugin.compcls \ - --component=B:flt.plugin.compcls \ - --params='flag=true, type=event' \ - --reset-base-params \ - --component=C:sink.plugin.compcls \ - --params='ratio=0.25' \ - --connect=A:B --connect=B:C +$ babeltrace2 run --base-params=offset=1203,flag=false \ + --component=A:src.plugin.compcls \ + --component=B:flt.plugin.compcls \ + --params=flag=true,type=event \ + --reset-base-params \ + --component=C:sink.plugin.compcls \ + --params=ratio=0.25 \ + --connect=A:B --connect=B:C ---- ==== @@ -339,8 +361,8 @@ and _any_ `A` output port, whatever its name, would be connected to a [role="term"] ---- $ babeltrace2 run --component=A:src.plug.my-src \ - --component=B:sink.plug.my-sink \ - --connect='A.foo*:B:nin*' --connect='A:B.oth*' + --component=B:sink.plug.my-sink \ + --connect='A.foo*:B:nin*' --connect='A:B.oth*' ---- Possible resulting graph: @@ -361,13 +383,15 @@ Possible resulting graph: include::common-cli-env.txt[] + include::common-cli-files.txt[] + include::common-cmd-footer.txt[] -SEE ALSO --------- +== SEE ALSO + +man:babeltrace2-intro(7), man:babeltrace2(1), -man:babeltrace2-convert(1), -man:babeltrace2-intro(7) +man:babeltrace2-convert(1) diff --git a/doc/man/babeltrace2-sink.ctf.fs.7.txt b/doc/man/babeltrace2-sink.ctf.fs.7.txt index aab42675..1e445b63 100644 --- a/doc/man/babeltrace2-sink.ctf.fs.7.txt +++ b/doc/man/babeltrace2-sink.ctf.fs.7.txt @@ -1,115 +1,243 @@ -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 <>). + +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 <> 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) diff --git a/doc/man/babeltrace2-sink.text.details.7.txt b/doc/man/babeltrace2-sink.text.details.7.txt new file mode 100644 index 00000000..dc879219 --- /dev/null +++ b/doc/man/babeltrace2-sink.text.details.7.txt @@ -0,0 +1,173 @@ += 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) diff --git a/doc/man/babeltrace2-sink.text.pretty.7.txt b/doc/man/babeltrace2-sink.text.pretty.7.txt index 3fd4ae1d..6d0cd292 100644 --- a/doc/man/babeltrace2-sink.text.pretty.7.txt +++ b/doc/man/babeltrace2-sink.text.pretty.7.txt @@ -1,55 +1,64 @@ -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: + -- @@ -67,81 +76,84 @@ param:color=(`never` | `auto` | `always`) (string):: 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) diff --git a/doc/man/babeltrace2-sink.utils.counter.7.txt b/doc/man/babeltrace2-sink.utils.counter.7.txt index 708cfa6f..60f051d5 100644 --- a/doc/man/babeltrace2-sink.utils.counter.7.txt +++ b/doc/man/babeltrace2-sink.utils.counter.7.txt @@ -1,87 +1,91 @@ -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) diff --git a/doc/man/babeltrace2-sink.utils.dummy.7.txt b/doc/man/babeltrace2-sink.utils.dummy.7.txt index cb4b52db..5ecf22a3 100644 --- a/doc/man/babeltrace2-sink.utils.dummy.7.txt +++ b/doc/man/babeltrace2-sink.utils.dummy.7.txt @@ -1,57 +1,57 @@ -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) diff --git a/doc/man/babeltrace2-source.ctf.fs.7.txt b/doc/man/babeltrace2-source.ctf.fs.7.txt index 19319917..f05a4d10 100644 --- a/doc/man/babeltrace2-source.ctf.fs.7.txt +++ b/doc/man/babeltrace2-source.ctf.fs.7.txt @@ -1,258 +1,257 @@ -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 +<>). ----- -/ - 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 <> 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 <> 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 <> 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 +<> 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) diff --git a/doc/man/babeltrace2-source.ctf.lttng-live.7.txt b/doc/man/babeltrace2-source.ctf.lttng-live.7.txt index d3b4f47e..6251b07c 100644 --- a/doc/man/babeltrace2-source.ctf.lttng-live.7.txt +++ b/doc/man/babeltrace2-source.ctf.lttng-live.7.txt @@ -1,74 +1,69 @@ -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] @@ -78,8 +73,9 @@ net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__ 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. @@ -88,33 +84,66 @@ net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__ 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] @@ -124,64 +153,47 @@ net[4]://__RDHOST__[:__RDPORT__] 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) diff --git a/doc/man/babeltrace2-source.text.dmesg.7.txt b/doc/man/babeltrace2-source.text.dmesg.7.txt index f24d4eec..9079fe4b 100644 --- a/doc/man/babeltrace2-source.text.dmesg.7.txt +++ b/doc/man/babeltrace2-source.text.dmesg.7.txt @@ -1,80 +1,105 @@ -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) diff --git a/doc/man/babeltrace2.1.txt b/doc/man/babeltrace2.1.txt index b2d69de0..beb4d679 100644 --- a/doc/man/babeltrace2.1.txt +++ b/doc/man/babeltrace2.1.txt @@ -1,187 +1,226 @@ -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'] ['<>'] ['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__]...] ['<>'] ['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 <>). +[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 <> 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 <> -for a list of plugins shipped with Babeltrace. +list the available plugins and what they offer. See +<> 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) diff --git a/doc/man/bt-asciidoc.conf b/doc/man/bt-asciidoc.conf index c7611d08..b9f768f3 100644 --- a/doc/man/bt-asciidoc.conf +++ b/doc/man/bt-asciidoc.conf @@ -1,3 +1,8 @@ +[specialcharacters] + +# LaTeX-like non-breaking space (disables subscript but we don't need it) +~=  + [macros] # command-line option in another man page macro @@ -35,16 +40,36 @@ # Usage: param:param-name (?su)[\\]?(?Pparam):(?P[a-zA-Z0-9_:.-]+(?nlqres):(?P[a-zA-Z0-9_:.-]+(?qres):(?P[a-zA-Z0-9_:.-]+(?compcls):(?P[a-zA-Z0-9_-]+)\.(?P[a-zA-Z0-9_-]+)\.(?P[a-zA-Z0-9_-]+)= -# not macro +# value object type +# +# Usage: vtype:[TYPE] +(?su)[\\]?(?Pvtype):\[(?P[^\]]+)\]= + +# not macro (emphasis) # # Usage: :not: :not:=not +# all macro (emphasis) +# +# Usage: :all: +:all:=all + # escstar macro # # Usage: :escstar: @@ -65,115 +90,81 @@ # Usage: :bs: :bs:=bs -# man macro expansions +# macro expansions for DocBook backend (begin) ifdef::doctype-manpage[] ifdef::backend-docbook[] + +# man macro expansions [man-inlinemacro] {target}{section} -endif::backend-docbook[] -endif::doctype-manpage[] # no link option macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [nlopt-inlinemacro] {opt} -endif::backend-docbook[] -endif::doctype-manpage[] # command-line option macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [opt-inlinemacro] {opt} -endif::backend-docbook[] -endif::doctype-manpage[] # command-line option in another man page macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [manopt-inlinemacro] {opt} -endif::backend-docbook[] -endif::doctype-manpage[] # component class initialization parameter macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [param-inlinemacro] {pname} -endif::backend-docbook[] -endif::doctype-manpage[] # no link component class initialization parameter macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [nlparam-inlinemacro] {pname} -endif::backend-docbook[] -endif::doctype-manpage[] + +# query result entry macro expansions +[qres-inlinemacro] +{pname} + +# no link query result entry macro expansions +[nlqres-inlinemacro] +{pname} # component class initialization parameter in another man page macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [manparam-inlinemacro] {pname} -endif::backend-docbook[] -endif::doctype-manpage[] # component class specification macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [compcls-inlinemacro] {cctype}.{ccplug}.{ccname} -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] \e* -endif::backend-docbook[] -endif::doctype-manpage[] # esccomma macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [esccomma-inlinemacro] \e, -endif::backend-docbook[] -endif::doctype-manpage[] # escdot macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [escdot-inlinemacro] \e, -endif::backend-docbook[] -endif::doctype-manpage[] # bs macro expansions -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [bs-inlinemacro] \e -endif::backend-docbook[] -endif::doctype-manpage[] # configure XML man page header -ifdef::doctype-manpage[] -ifdef::backend-docbook[] [header] template::[header-declarations] @@ -185,11 +176,13 @@ template::[header-declarations] {manvolnum} Babeltrace {babeltrace_version} - Babeltrace manual + Babeltrace 2 manual {manname} {manpurpose} + +# macro expansions for DocBook backend (end) endif::backend-docbook[] endif::doctype-manpage[] diff --git a/doc/man/common-cli-env.txt b/doc/man/common-cli-env.txt index 82e1b740..9ae62354 100644 --- a/doc/man/common-cli-env.txt +++ b/doc/man/common-cli-env.txt @@ -1,16 +1,31 @@ -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`. diff --git a/doc/man/common-cli-files.txt b/doc/man/common-cli-files.txt index c9659cea..0bafeb75 100644 --- a/doc/man/common-cli-files.txt +++ b/doc/man/common-cli-files.txt @@ -1,7 +1,10 @@ -FILES ------ +== FILES + `$HOME/.local/lib/babeltrace2/plugins`:: User plugin directory. +{system_plugin_path}+:: System plugin directory. + ++{system_plugin_provider_path}+:: + System plugin provider directory. diff --git a/doc/man/common-cmd-footer.txt b/doc/man/common-cmd-footer.txt index b1967305..86a8a70a 100644 --- a/doc/man/common-cmd-footer.txt +++ b/doc/man/common-cmd-footer.txt @@ -1,5 +1,5 @@ -EXIT STATUS ------------ +== EXIT STATUS + *0* on success, *1* otherwise. diff --git a/doc/man/common-cmd-info-options.txt b/doc/man/common-cmd-info-options.txt index ecc1041e..03c177eb 100644 --- a/doc/man/common-cmd-info-options.txt +++ b/doc/man/common-cmd-info-options.txt @@ -1,4 +1,5 @@ -Command information -~~~~~~~~~~~~~~~~~~~ -opt:-h, opt:--help:: +=== Command information + +opt:-h:: +opt:--help:: Show the command's help and quit. diff --git a/doc/man/common-cmd-params-format.txt b/doc/man/common-cmd-params-format.txt index c8cefc0e..1e84571c 100644 --- a/doc/man/common-cmd-params-format.txt +++ b/doc/man/common-cmd-params-format.txt @@ -1,14 +1,12 @@ -[[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: @@ -31,22 +29,29 @@ list of `NAME=VALUE` assignments: * 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. diff --git a/doc/man/common-cmd-plugin-path.txt b/doc/man/common-cmd-plugin-path.txt deleted file mode 100644 index 8527de9f..00000000 --- a/doc/man/common-cmd-plugin-path.txt +++ /dev/null @@ -1,19 +0,0 @@ -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. diff --git a/doc/man/common-common-compat-env.txt b/doc/man/common-common-compat-env.txt deleted file mode 100644 index 3c2f3ed9..00000000 --- a/doc/man/common-common-compat-env.txt +++ /dev/null @@ -1,23 +0,0 @@ -`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. --- diff --git a/doc/man/common-common-env.txt b/doc/man/common-common-env.txt new file mode 100644 index 00000000..099635b7 --- /dev/null +++ b/doc/man/common-common-env.txt @@ -0,0 +1,17 @@ +`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. +-- diff --git a/doc/man/common-convert-examples.txt b/doc/man/common-convert-examples.txt new file mode 100644 index 00000000..b82e0688 --- /dev/null +++ b/doc/man/common-convert-examples.txt @@ -0,0 +1,132 @@ +.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 +---- +==== diff --git a/doc/man/common-ctf-plugin-env.txt b/doc/man/common-ctf-plugin-env.txt deleted file mode 100644 index 4b8affd5..00000000 --- a/doc/man/common-ctf-plugin-env.txt +++ /dev/null @@ -1,16 +0,0 @@ -`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). diff --git a/doc/man/common-footer.txt b/doc/man/common-footer.txt index 7cbe6956..a01534d6 100644 --- a/doc/man/common-footer.txt +++ b/doc/man/common-footer.txt @@ -1,36 +1,38 @@ -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]. diff --git a/doc/man/common-gen-options.txt b/doc/man/common-gen-options.txt index 413f3050..925cf56b 100644 --- a/doc/man/common-gen-options.txt +++ b/doc/man/common-gen-options.txt @@ -1,18 +1,27 @@ -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`. diff --git a/doc/man/common-lib-env.txt b/doc/man/common-lib-env.txt index dc7c9779..6c5ba809 100644 --- a/doc/man/common-lib-env.txt +++ b/doc/man/common-lib-env.txt @@ -1,20 +1,52 @@ -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[] +-- diff --git a/doc/man/common-log-levels.txt b/doc/man/common-log-levels.txt new file mode 100644 index 00000000..5875dc9b --- /dev/null +++ b/doc/man/common-log-levels.txt @@ -0,0 +1,46 @@ +`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. diff --git a/doc/man/common-plugin-path-options.txt b/doc/man/common-plugin-path-options.txt deleted file mode 100644 index 7e114fa3..00000000 --- a/doc/man/common-plugin-path-options.txt +++ /dev/null @@ -1,11 +0,0 @@ -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. diff --git a/doc/man/common-ppp-env.txt b/doc/man/common-ppp-env.txt deleted file mode 100644 index 49cc7720..00000000 --- a/doc/man/common-ppp-env.txt +++ /dev/null @@ -1,6 +0,0 @@ -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). diff --git a/doc/man/common-see-babeltrace2-intro.txt b/doc/man/common-see-babeltrace2-intro.txt new file mode 100644 index 00000000..70bbfc33 --- /dev/null +++ b/doc/man/common-see-babeltrace2-intro.txt @@ -0,0 +1,2 @@ +See man:babeltrace2-intro(7) to learn more about the Babeltrace~2 +project and its core concepts. diff --git a/doc/man/common-trimmer-time-format.txt b/doc/man/common-trimmer-time-format.txt new file mode 100644 index 00000000..3c74bc30 --- /dev/null +++ b/doc/man/common-trimmer-time-format.txt @@ -0,0 +1,28 @@ +[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. -- 2.34.1