WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
-INPUT = "@top_srcdir@/include/babeltrace/ctf-ir" \
- "@top_srcdir@/include/babeltrace/component" \
- "@top_srcdir@/include/babeltrace/plugin" \
- "@top_srcdir@/include/babeltrace/ref.h" \
- "@top_srcdir@/include/babeltrace/values.h" \
- "@top_srcdir@/include/babeltrace/logging.h" \
- "@top_srcdir@/include/babeltrace/types.h" \
+INPUT = "@top_srcdir@/include/babeltrace2/ctf-ir" \
+ "@top_srcdir@/include/babeltrace2/component" \
+ "@top_srcdir@/include/babeltrace2/plugin" \
+ "@top_srcdir@/include/babeltrace2/ref.h" \
+ "@top_srcdir@/include/babeltrace2/values.h" \
+ "@top_srcdir@/include/babeltrace2/logging.h" \
+ "@top_srcdir@/include/babeltrace2/types.h" \
"@srcdir@/dox/main-page.dox" \
"@srcdir@/dox/includes-build.dox" \
"@srcdir@/dox/write-plugin.dox" \
@section includefiles Include files
You can find all the Babeltrace library include files (C headers) in the
-\c babeltrace directory under the include files directory chosen when
+\c babeltrace2 directory under the include files directory chosen when
installing Babeltrace. By default, this is <code>/usr/include</code>.
If you build Babeltrace from source without specifying an installation
prefix, this is <code>/usr/local/include</code>.
Multiple types of applications can use the Babeltrace library:
-- A user plugin (shared object) to be loaded by the \c babeltrace
+- A user plugin (shared object) to be loaded by the \c babeltrace2
converter program or by another application.
- A user application or library which loads plugins to manually connect
existing components in a specific way.
- A user application or library which creates its own component classes
and manually connects them.
-In any way, the only library to link to is `libbabeltrace`.
+In any way, the only library to link to is `libbabeltrace2`.
@subsection howtobuildplugin Build a plugin
<li>Create the plugin shared object:
@verbatim
-cc -shared my-plugin.o -lbabeltrace -o my-plugin.so
+cc -shared my-plugin.o -lbabeltrace2 -o my-plugin.so
@endverbatim
</li>
</ol>
<li>Create the executable application:
@verbatim
-cc my-app.o -lbabeltrace -o my-app
+cc my-app.o -lbabeltrace2 -o my-app
@endverbatim
</li>
</ol>
# List only the names without the .*.txt extension here:
MAN1_NAMES = \
- babeltrace \
- babeltrace-convert \
- babeltrace-help \
- babeltrace-list-plugins \
- babeltrace-log \
- babeltrace-query \
- babeltrace-run
-MAN7_NAMES = babeltrace-filter.utils.muxer \
- babeltrace-filter.utils.trimmer \
- babeltrace-intro \
- babeltrace-plugin-ctf \
- babeltrace-plugin-text \
- babeltrace-plugin-utils \
- babeltrace-sink.ctf.fs \
- babeltrace-sink.text.pretty \
- babeltrace-sink.utils.counter \
- babeltrace-sink.utils.dummy \
- babeltrace-source.ctf.fs \
- babeltrace-source.ctf.lttng-live \
- babeltrace-source.text.dmesg
+ babeltrace2 \
+ babeltrace2-convert \
+ babeltrace2-help \
+ babeltrace2-list-plugins \
+ babeltrace2-log \
+ babeltrace2-query \
+ babeltrace2-run
+MAN7_NAMES = babeltrace2-filter.utils.muxer \
+ babeltrace2-filter.utils.trimmer \
+ babeltrace2-intro \
+ babeltrace2-plugin-ctf \
+ babeltrace2-plugin-text \
+ babeltrace2-plugin-utils \
+ babeltrace2-sink.ctf.fs \
+ babeltrace2-sink.text.pretty \
+ babeltrace2-sink.utils.counter \
+ babeltrace2-sink.utils.dummy \
+ babeltrace2-source.ctf.fs \
+ babeltrace2-source.ctf.lttng-live \
+ babeltrace2-source.text.dmesg
MAN1_NO_ASCIIDOC_NAMES =
MAN7_NO_ASCIIDOC_NAMES =
if ENABLE_DEBUG_INFO
MAN7_NAMES += \
- babeltrace-plugin-lttng-utils \
- babeltrace-filter.lttng-utils.debug-info
+ babeltrace2-plugin-lttng-utils \
+ babeltrace2-filter.lttng-utils.debug-info
endif
# AsciiDoc sources and outputs
Main program::
+__program__.1.txt+
-`babeltrace(1)` command::
- +babeltrace-__command__.1.txt+
+`babeltrace2(1)` command::
+ +babeltrace2-__command__.1.txt+
Babeltrace introduction::
- `babeltrace-intro.7.txt`
+ `babeltrace2-intro.7.txt`
Babeltrace plugin::
- +babeltrace-plugin-__plugin__.7.txt+
+ +babeltrace2-plugin-__plugin__.7.txt+
Babeltrace plugin's component class::
- +babeltrace-__type__.__plugin__.__compcls__.7.txt+
+ +babeltrace2-__type__.__plugin__.__compcls__.7.txt+
== Macros
+__page__+ in section +__section__+. In troff, the man page's name
is rendered in bold.
+
-Example: `man:babeltrace-convert(1)`
+Example: `man:babeltrace2-convert(1)`
+opt:__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__+.
+
-Example: `manopt:babeltrace(1):--log-level`,
-+manopt:babeltrace-convert(1):--component=\`source.ctf.fs`+
+Example: `manopt:babeltrace2(1):--log-level`,
++manopt:babeltrace2-convert(1):--component=\`source.ctf.fs`+
+nlopt:__name__+::
Use this macro to write a command-line option named +__name__+
[attributes]
# default values
-system_plugin_path="@LIBDIR@/babeltrace/plugins"
+system_plugin_path="@LIBDIR@/babeltrace2/plugins"
babeltrace_version="@PACKAGE_VERSION@"
enable_debug_info="@ENABLE_DEBUG_INFO_VAL@"
+++ /dev/null
-babeltrace-convert(1)
-=====================
-:manpagetype: command
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-convert - Convert one or more traces
-
-
-SYNOPSIS
---------
-Convert one or more traces:
-
-[verse]
-*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- [opt:--run-args | opt:--run-args-0] [opt:--retry-duration='DURUS']
- 'CONVERSION ARGUMENTS'
-
-Print the metadata text of a CTF trace:
-
-[verse]
-*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- [opt:--output='OUTPATH']
- opt:--output-format=`ctf-metadata` 'TRACE-PATH'
-
-Print the available http://lttng.org/docs/#doc-lttng-live[LTTng live]
-sessions:
-
-[verse]
-*babeltrace convert* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- [opt:--output='OUTPATH'] opt:--input-format=`lttng-live` 'URL'
-
-
-DESCRIPTION
------------
-The `convert` command creates a trace conversion graph and runs it.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-[NOTE]
-====
-`convert` is the default man:babeltrace(1) command: you usually don't
-need to specify its name. The following commands are equivalent
-if the `...` part does not start with another man:babeltrace(1)
-command's name, like `run` or `list-plugins`:
-
-[role="term"]
-----
-$ babeltrace convert ...
-$ babeltrace ...
-----
-
-If you need to make sure that you are executing the `convert` command,
-use `babeltrace convert` explicitly.
-====
-
-A conversion graph is a specialized trace processing graph focused on
-the conversion of one or more traces to another format, possibly
-filtering their events and other notifications in the process. A
-conversion graph is a linear chain of components after the source
-streams are merged:
-
-----
-+----------+
-| source 1 |-.
-+----------+ |
- | +-------+
-+----------+ '->| | +---------+ +------------+
-| source 2 |--->| muxer |--->| trimmer |--->| debug-info |-.
-+----------+ .->| | +---------+ +------------+ |
- | +-------+ |
-+----------+ | .----------------------------------------'
-| ... |-' | +---------------+ +------+
-+----------+ '->| other filters |--->| sink |
- +---------------+ +------+
-----
-
-Note that the trimmer, debugging information, and other filters are
-optional. See <<comp-create-impl,Create implicit components>> to learn
-how to enable them.
-
-If you need another processing graph layout, use the more flexible
-man:babeltrace-run(1) command.
-
-Like with the man:babeltrace-run(1) command, you can create components
-explicitly with the opt:--component option (see
-<<comp-create-expl,Create explicit components>>). You can also use one
-of the many specific `convert` command options and arguments to create
-implicit components from known component classes (see
-<<comp-create-impl,Create implicit components>>). For example, you can
-specify a single path argument to print the merged events of a CTF trace
-on the console:
-
-[role="term"]
-----
-$ babeltrace /path/to/trace
-----
-
-This is the equivalent of creating and connecting together:
-
-* A compcls:src.ctf.fs component with its manparam:source.ctf.fs:path
- initialization parameter set to `/path/to/trace`.
-
-* A compcls:filter.utils.muxer component.
-
-* A compcls:sink.text.pretty component.
-
-This creates the following conversion graph:
-
-----
-+------------+ +--------------------+ +------------------+
-| src.ctf.fs | | filter.utils.muxer | | sink.text.pretty |
-| [ctf-fs] | | [muxer] | | [pretty] |
-| | | | | |
-| stream0 @--->@ out @--->@ in |
-| stream1 @--->@ | +------------------+
-| stream2 @--->@ |
-| stream3 @--->@ |
-+------------+ +--------------------+
-----
-
-It is equivalent to the following command:
-
-[role="term"]
-----
-$ babeltrace run --component=ctf-fs:src.ctf.fs \
- --params=path=/path/to/trace \
- --component=pretty:sink.text.pretty \
- --component=muxer:filter.utils.muxer \
- --connect=ctf-fs:muxer --connect=muxer:pretty
-----
-
-You can use the opt:--run-args option to make the `convert` command
-print its equivalent man:babeltrace-run(1) arguments instead of
-creating and running the conversion graph. The printed arguments are
-escaped for shells, which means you can use them as is on the command
-line and possibly add more options to the `run` command:
-
-[role="term"]
-----
-$ babeltrace run $(babeltrace --run-args /path/to/trace) ...
-----
-
-The opt:--run-args-0 option is like the opt:--run-args option, but the
-printed arguments are :not: escaped and they are separated by a null
-character instead of a space. This is useful if the resulting arguments
-are not the direct input of a shell, for example if passed to
-`xargs -0`.
-
-See <<examples,EXAMPLES>> for usage examples.
-
-
-[[comp-create-expl]]
-Create explicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-To explicitly create a component, use the opt:--component option. This
-option specifies:
-
-* **Optional**: The name of the component instance. You can also use the
- opt:--name option for this.
-
-* The type of the component class to instantiate: source, filter, or
- sink.
-
-* The name of the plugin in which to find the component class to
- instantiate.
-
-* The name of the component class to instantiate.
-
-You can use the opt:--component option multiple times to create
-multiple components. You can instantiate the same component class
-multiple times as different component instances.
-
-Immediately following a opt:--component option on the command line, the
-created component is known as the _current component_ (until the next
-opt:--component option).
-
-The following, optional command-line options apply to the current
-component:
-
-opt:--name='NAME'::
- Set the name of the current component to 'NAME'.
-
-opt:--params='PARAMS'::
- Add 'PARAMS' to the initialization parameters of the current
- component. If 'PARAMS' contains a key which exists in the current
- component's initialization parameters, this parameter is replaced.
-+
-See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
-
-opt:--path='PATH'::
- Set the nlparam:path initialization parameter of the current
- component to 'PATH' (replace the parameter if it exists).
-+
-You can use this option instead of manually specifying `path="PATH"` in
-a opt:--params option to use your shell's tilde expansion (`~`). Tilde
-expansion requires the tilde to be the first character of the argument,
-which is not possible with `path="PATH"`.
-
-opt:--url='URL'::
- Set the nlparam:url initialization parameter of the current
- component to 'URL' (replace the parameter if it exists).
-
-See <<examples,EXAMPLES>> for usage examples.
-
-
-[[comp-create-impl]]
-Create implicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-An _implicit component_ is a component which is created and added to the
-conversion graph without an explicit instantiation through the
-opt:--component option. An implicit component is easier to create than
-an explicit component: this is why the `convert` command exists, as you
-can also create and run a conversion graph with the generic
-man:babeltrace-run(1) command.
-
-There are many ways to create implicit components with the `convert`
-command:
-
-* To create one or more implicit compcls:src.ctf.fs components (CTF
- trace read from the file system), use one or more positional arguments
- to specify the paths to the CTF traces to read, and do :not: specify
- the opt:--input-format=`lttng-live` option.
-+
-Example:
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace /path/to/other/trace
-----
-+
-The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_
-the implicit compcls:src.ctf.fs components. For example:
-+
-[role="term"]
-----
-$ babeltrace --clock-offset=3 trace1 trace2
-----
-+
-With the command line above, two implicit compcls:src.ctf.fs components
-have their manparam:source.ctf.fs:clock-class-offset-s initialization
-parameter set to `3`, but they have different
-manparam:source.ctf.fs:path parameters (`trace1` and `trace2`).
-+
-You cannot create implicit compcls:src.ctf.fs components and an implicit
-compcls:src.ctf.lttng-live component.
-
-* To create an implicit compcls:src.ctf.lttng-live component
- (http://lttng.org/docs/#doc-lttng-live[LTTng live] input), specify the
- opt:--input-format=`lttng-live` option and the LTTng relay daemon's
- URL with the positional argument.
-+
-Example:
-+
-[role="term"]
-----
-$ babeltrace --input-format=lttng-live \
- net://localhost/host/abeille/my-session
-----
-+
-You cannot create an implicit compcls:src.ctf.lttng-live component and
-implicit compcls:src.ctf.fs components.
-
-* To create an implicit compcls:filter.utils.trimmer component (trace
- trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
- option.
-+
-Examples:
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --begin=22:14:38 --end=22:15:07
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --timerange=22:14:38,22:15:07
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --end=12:31:04.882928015
-----
-
-* To create an implicit compcls:filter.lttng-utils.debug-info (add
- debugging information to compatible LTTng events), specify any of the
- opt:--debug-info, opt:--debug-info-dir, opt:--debug-info-full-path, or
- opt:--debug-info-target-prefix options.
-+
-Examples:
-+
-[role="term"]
-----
-$ babeltrace --debug-info /path/to/trace
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace \
- --debug-info-target-prefix=/tmp/tgt-root
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --debug-info-full-path
-----
-
-* To create an implicit compcls:sink.text.pretty component
- (pretty-printing text output to the console or to a file), do any of:
-+
---
-* Specify no other sink components, <<comp-create-expl,explicit>> or
- implicit. The compcls:sink.text.pretty implicit component is the
- _default_ implicit sink component. If any other explicit or implicit
- component exists, the default compcls:sink.text.pretty sink component
- is not automatically created.
-
-* Specify any of the opt:--clock-cycles, opt:--clock-date,
- opt:--clock-gmt, opt:--clock-seconds, opt:--color, opt:--fields,
- opt:--names, or opt:--no-delta options. You can also specify the
- opt:--output option without using the opt:--output-format=`ctf` option
- (in which case opt:--output applies to the implicit
- compcls:sink.ctf.fs component).
-
-* Specify the opt:--output-format=`text` option.
---
-+
-Examples:
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --no-delta
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --output-format=text
-----
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --output=/tmp/pretty-out
-----
-
-* To create an implicit compcls:sink.utils.dummy component (dummy
- output), specify the opt:--output-format=`dummy` option. This option
- disables the default implicit compcls:sink.text.pretty component.
-+
-Example:
-+
-[role="term"]
-----
-$ babeltrace /path/to/trace --output-format=dummy
-----
-
-* To create an implicit compcls:sink.ctf.fs component (CTF traces
- written to the file system), specify the opt:--output-format=`ctf`
- option. This option disables the default implicit
- compcls:sink.text.pretty component. Use the opt:--output option to
- specify the output directory.
-+
-Example:
-+
-[role="term"]
-----
-$ babeltrace /path/to/input/trace --output-format=ctf \
- --output=my-traces
-----
-
-You can combine multiple methods to create implicit components. For
-example, you can trim an LTTng (CTF) trace, add debugging information to
-it, and write it as another CTF trace:
-
-[role="term"]
-----
-$ babeltrace /path/to/input/trace --timerange=22:14:38,22:15:07 \
- --debug-info --output-format=ctf --output=out-dir
-----
-
-The equivalent man:babeltrace-run(1) command of this `convert` command
-is:
-
-[role="term"]
-----
-$ babeltrace run --component=src-ctf-fs:src.ctf.fs \
- --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
-----
-
-See <<examples,EXAMPLES>> for more examples.
-
-
-include::common-cmd-params-format.txt[]
-
-
-[[time-fmt]]
-Time option format
-~~~~~~~~~~~~~~~~~~
-The format of the arguments of the opt:--begin and opt:--end options
-is:
-
-[verse]
-$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
-
-'YYYY'::
- 4-digit year.
-
-'MM'::
- 2-digit month (January is `01`).
-
-'DD'::
- 2-digit day.
-
-'hh'::
- 2-digit hour (24-hour format).
-
-'mm'::
- 2-digit minute.
-
-'ss'::
- 2-digit second.
-
-'nnnnnnnnn'::
- 9-digit nanosecond.
-
-
-include::common-cmd-plugin-path.txt[]
-
-
-OPTIONS
--------
-include::common-gen-options.txt[]
-
-
-Explicit component creation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-See <<comp-create-expl,Create explicit components>> to learn how to
-use the following options.
-
-opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
- Create a component initially named 'NAME' (if specified) from the
- component class of type 'TYPE' named 'COMPCLS' found in the plugin
- named 'PLUGIN', and set it as the current component.
-+
-The available values for 'TYPE' are:
-+
---
-`source`::
-`src`::
- Source component class.
-
-`filter`::
-`flt`::
- Filter component class.
-
-`sink`::
- Sink component class.
---
-
-opt:--name='NAME'::
- Set the name of the current component to 'NAME'. The names of all
- the explicitly created components in the conversion graph must be
- unique.
-
-opt:-p 'PARAMS', opt:--params='PARAMS'::
- Add 'PARAMS' to the initialization parameters of the current
- component. If 'PARAMS' contains a key which exists in the current
- component's initialization parameters, replace the parameter.
- See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
-
-opt:-P 'PATH', opt:--path='PATH'::
- Set the nlparam:path initialization parameter of the current
- component to 'PATH' (replace the parameter if it exists).
-
-opt:-u 'URL', opt:--url='URL'::
- Set the nlparam:url initialization parameter of the current
- component to 'URL' (replace the parameter if it exists).
-
-
-Legacy options to create implicit components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-opt:-i 'FORMAT', opt:--input-format='FORMAT'::
- Create one or more implicit source components. The available values
- for 'FORMAT' are:
-+
---
-`ctf`::
- Create an implicit compcls:src.ctf.fs component for each positional
- argument. Each positional argument sets the
- manparam:source.ctf.fs:path initialization parameter of an
- individual component. See <<impl-opts-ctf,Implicit
- compcls:src.ctf.fs component>>.
-+
-See man:babeltrace-source.ctf.fs(7) to learn more about this
-component class.
-
-`lttng-live`::
- Depending on the format of the positional argument:
-+
---
-`net[4]://RDHOST[:RDPORT]/host/TGTHOST`::
- Print the available LTTng live sessions of the LTTng relay daemon at
- the address `RDHOST` and port `RDPORT`, and then exit.
-
-`net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`::
- Create an implicit compcls:src.ctf.lttng-live component. The
- position argument sets the manparam:source.ctf.lttng-live:url
- parameter of the component.
-+
-Any other format for the positional argument is invalid.
-+
-See man:babeltrace-source.ctf.lttng-live(7) to learn more about
-this component class.
---
---
-+
-You can specify at most one opt:--input-format option.
-
-opt:-o 'FORMAT', opt:--output-format='FORMAT'::
- Create an implicit sink component. The available values for 'FORMAT'
- are:
-+
---
-`text`::
- Create an implicit compcls:sink.text.pretty component.
- See <<impl-opts-text,Implicit compcls:sink.text.pretty component>>.
-+
-See man:babeltrace-sink.text.pretty(7) to learn more about
-this component class.
-
-`ctf`::
- Create an implicit compcls:sink.ctf.fs component. Specify the output
- path with the opt:--output option.
-+
-See man:babeltrace-sink.ctf.fs(7) to learn more about
-this component class.
-
-`dummy`::
- Create an implicit compcls:sink.utils.dummy component.
-+
-See man:babeltrace-sink.utils.dummy(7) to learn more about
-this component class.
-
-`ctf-metadata`::
- Print the metadata text of a CTF trace and exit. The first
- positional argument specifies the path to the CTF trace.
---
-+
-You can specify at most one opt:--output-format option.
-
-
-[[impl-opts-ctf]]
-Implicit compcls:src.ctf.fs component(s)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is one implicit compcls:src.ctf.fs component per positional
-argument (which are trace paths), unless you specify
-opt:--input-format=`lttng-live`.
-
-See man:babeltrace-source.ctf.fs(7) to learn more about this
-component class.
-
-opt:--clock-offset='SEC'::
- Set the manparam:source.ctf.fs:clock-class-offset-s initialization
- parameter of all the implicit compcls:src.ctf.fs components to
- 'SEC'.
-+
-The manparam:source.ctf.fs:clock-class-offset-s initialization parameter
-adds 'SEC' seconds to the offsets of all the clock classes that the
-component creates.
-+
-You can combine this option with opt:--clock-offset-ns.
-
-opt:--clock-offset-ns='NS'::
- Set the manparam:source.ctf.fs:clock-class-offset-ns initialization
- parameter of all the implicit compcls:src.ctf.fs components to
- 'NS'.
-+
-The manparam:source.ctf.fs:clock-class-offset-ns initialization
-parameter adds 'NS' nanoseconds to the offsets of all the clock classes
-that the component creates.
-+
-You can combine this option with opt:--clock-offset-s.
-
-
-Implicit compcls:filter.utils.trimmer component
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you specify at least one of the following options, you create an
-implicit compcls:filter.utils.trimmer component.
-
-See man:babeltrace-filter.utils.trimmer(7) to learn more about
-this component class.
-
-See <<time-fmt,Time option format>> for the format of 'BEGIN' and 'END'.
-
-opt:--begin='BEGIN'::
- Set the manparam:filter.utils.trimmer:begin initialization parameter
- of the component to 'BEGIN'. You cannot use this option with the
- opt:--timerange option.
-
-opt:--end='END'::
- Set the manparam:filter.utils.trimmer:end initialization parameter
- of the component to 'END'. You cannot use this option with the
- opt:--timerange option.
-
-opt:--timerange='BEGIN','END'::
- Equivalent to opt:--begin='BEGIN' opt:--end='END'.
-+
-You can also surround the whole argument with `[` and `]`.
-
-
-Implicit compcls:filter.lttng-utils.debug-info component
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you specify at least one of the following options, you create an
-implicit compcls:filter.lttng-utils.debug-info component. This component
-only alters compatible LTTng events.
-
-See man:babeltrace-filter.lttng-utils.debug-info(7) to learn more
-about this component class.
-
-opt:--debug-info::
- Create an implicit compcls:filter.lttng-utils.debug-info component.
- This option is useless if you specify any of the options below.
-
-opt:--debug-info-dir='DIR'::
- Set the manparam:filter.lttng-utils.debug-info:debug-info-dir
- initialization parameter of the component to 'DIR'.
-+
-The manparam:filter.lttng-utils.debug-info:debug-info-dir parameter
-indicates where the component should find the debugging information it
-needs if it's not found in the actual executable files.
-
-opt:--debug-info-full-path::
- Set the manparam:filter.lttng-utils.debug-info:full-path
- initialization parameter of the component to true.
-+
-When the manparam:filter.lttng-utils.debug-info:full-path parameter is
-true, the component writes the full (absolute) paths to files in its
-debugging information fields instead of just the short names.
-
-opt:--debug-info-target-prefix='PREFIX'::
- Set the manparam:filter.lttng-utils.debug-info:target-prefix
- initialization parameter of the component to 'PREFIX'.
-+
-The manparam:filter.lttng-utils.debug-info:target-prefix parameter is a
-path to prepend to the paths to executables recorded in the trace. For
-example, if a trace contains the executable path `/usr/bin/ls` in its
-state dump events, and you specify
-opt:--debug-info-target-prefix=`/home/user/boards/xyz/root`, then the
-component opens the `/home/user/boards/xyz/root/usr/bin/ls` file to find
-debugging information.
-
-
-[[impl-opts-text]]
-=== Implicit compcls:sink.text.pretty component
-
-If you specify at least one of the following options, you create an
-implicit compcls:sink.text.pretty component. The `convert` command also
-creates a default implicit compcls:sink.text.pretty component if no
-other sink component exists.
-
-See man:babeltrace-sink.text.pretty(7) to learn more about this
-component class.
-
-opt:--clock-cycles::
- Set the manparam:sink.text.pretty:clock-seconds initialization
- parameter of the component to true.
-+
-The manparam:sink.text.pretty:clock-cycles parameter makes the component
-print the event time in clock cycles.
-
-opt:--clock-date::
- Set the manparam:sink.text.pretty:clock-date initialization
- parameter of the component to true.
-+
-The manparam:sink.text.pretty:clock-date parameter makes the component
-print the date and the time of events.
-
-opt:--clock-gmt::
- Set the manparam:sink.text.pretty:clock-gmt initialization parameter
- of the component to true.
-+
-The manparam:sink.text.pretty:clock-gmt parameter makes the component
-not apply the local timezone to the printed times.
-
-opt:--clock-seconds::
- Set the manparam:sink.text.pretty:clock-seconds initialization
- parameter of the component to true.
-+
-The manparam:sink.text.pretty:clock-seconds parameter makes the
-component print the event times in seconds since Epoch.
-
-opt:--color='WHEN'::
- Set the manparam:sink.text.pretty:color initialization parameter of
- the component to 'WHEN'.
-+
-The available values for 'WHEN' are:
-+
---
-`auto`::
- Automatic color support depending on the capabilities of the
- terminal(s) to which the standard output and error streams are
- connected.
-
-`never`::
- Never emit terminal color codes.
-
-`always`::
- Always emit terminal color codes.
---
-+
-The `auto` and `always` values have no effect if the
-`BABELTRACE_TERM_COLOR` environment variable is set to `NEVER`.
-
-opt:--fields='FIELD'[,'FIELD']...::
- For each 'FIELD', set the nlparam:field-FIELD initialization
- parameter of the component to true.
-+
-For example, opt:--fields=`trace,loglevel,emf` sets the
-manparam:sink.text.pretty:field-trace,
-manparam:sink.text.pretty:field-loglevel, and
-manparam:sink.text.pretty:field-emf initialization parameters to true.
-+
-The available value for 'FIELD' are:
-+
-* `trace`
-* `trace:hostname`
-* `trace:domain`
-* `trace:procname`
-* `trace:vpid`
-* `loglevel`
-* `emf`
-* `callsite`
-
-opt:--names='NAME'[,'NAME']...::
- For each 'NAME', set the nlparam:name-NAME initialization parameter
- of the component to true.
-+
-For example, opt:--names=`payload,scope` sets the
-manparam:sink.text.pretty:name-payload and
-manparam:sink.text.pretty:name-scope initialization parameters to true.
-+
-The available value for 'NAME' are:
-+
-* `payload`
-* `context`
-* `scope`
-* `header`
-
-opt:--no-delta::
- Set the manparam:sink.text.pretty:no-delta initialization parameter
- of the component to true.
-+
-When the manparam:sink.text.pretty:no-delta parameter is true, the
-component does not print the duration since the last event on the line.
-
-
-Shared options
-~~~~~~~~~~~~~~
-opt:-w 'PATH', opt:--output='PATH'::
- 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.
-+
-When you specify opt:--output-format=`ctf`, set the
-manparam:sink.ctf.fs:path initialization parameter of the implicit
-compcls:sink.ctf.fs component to 'PATH'. Otherwise, create an implicit
-compcls:sink.text.pretty component and set its
-manparam:sink.text.pretty:path initialization parameter to 'PATH'.
-+
-See man:babeltrace-sink.ctf.fs(7) and
-man:babeltrace-sink.text.pretty(7) to learn more about those
-component classes.
-
-
-Equivalent `babeltrace run` arguments
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-opt:--run-args::
- Print the equivalent man:babeltrace-run(1) arguments instead of
- creating and running the conversion graph. The printed arguments are
- space-separated and individually escaped for safe shell input.
-+
-You cannot use this option with the opt:--run-args-0 or
-opt:--stream-intersection option.
-
-opt:--run-args-0::
- Print the equivalent man:babeltrace-run(1) arguments instead of
- creating and running the conversion graph. The printed arguments are
- separated with a null character and :not: escaped for safe shell
- input.
-+
-You cannot use this option with the opt:--run-args or
-opt:--stream-intersection option.
-
-
-Conversion graph configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-opt:--retry-duration='DURUS'::
- Set the duration of a single retry to 'DURUS'{nbsp}µs when a
- component reports "try again later" (busy network or file system,
- for example).
-+
-Default: 100000 (100{nbsp}ms).
-
-opt:--stream-intersection::
- Enable the stream intersection mode. In this mode, for each trace,
- the `convert` command filters out the events and other notifications
- which are not in the time range where _all_ the trace's streams are
- active.
-+
-All the source components, <<comp-create-expl,explicit>> and
-<<comp-create-impl,implicit>>, must have classes which support the
-`trace-info` query object to use this option. The only Babeltrace
-project's component class which supports this query object is
-compcls:source.ctf.fs.
-+
-Because it is not possible to replicate with a single
-man:babeltrace-run(1) command line what the `convert` method does with
-the opt:--stream-intersection option, you cannot use this option with
-the opt:--run-args or opt:--run-args-0 option.
-
-
-Plugin path
-~~~~~~~~~~~
-opt:--omit-home-plugin-path::
- Do not search for plugins in `$HOME/.local/lib/babeltrace/plugins`.
-
-opt:--omit-system-plugin-path::
- Do not search for plugins in +{system_plugin_path}+.
-
-opt:--plugin-path='PATH'[:__PATH__]...::
- Add 'PATH' to the list of paths in which dynamic plugins can be
- found.
-
-
-Command information
-~~~~~~~~~~~~~~~~~~~
-opt:-h, opt:--help::
- Show command help and quit.
-
-
-[[examples]]
-EXAMPLES
---------
-.Pretty-print the events of one or more CTF traces.
-====
-[role="term"]
-----
-$ babeltrace my-trace
-----
-
-[role="term"]
-----
-$ babeltrace my-traces
-----
-
-[role="term"]
-----
-$ babeltrace my-trace-1 my-trace-2 my-trace-3
-----
-====
-
-.Trim a CTF trace and pretty-print the events.
-====
-[role="term"]
-----
-$ babeltrace my-trace --begin=22:55:43.658582931 \
- --end=22:55:46.967687564
-----
-
-[role="term"]
-----
-$ babeltrace my-trace --begin=22:55:43.658582931
-----
-
-[role="term"]
-----
-$ babeltrace my-trace --end=22:55:46.967687564
-----
-
-[role="term"]
-----
-$ babeltrace my-trace --timerange=22:55:43,22:55:46.967687564
-----
-====
-
-.Trim a CTF trace, enable the stream intersection mode, and generate a CTF trace.
-====
-[role="term"]
-----
-$ babeltrace my-trace --stream-intersection \
- --timerange=22:55:43,22:55:46.967687564 \
- --output-format=ctf --output=out-trace
-----
-====
-
-.Record LTTng live traces to the file system (as CTF traces).
-====
-[role="term"]
-----
-$ babeltrace --input-format=lttng-live \
- net://localhost/host/myhostname/auto-20170411-134512 \
- --output-format=ctf --output=/path/to/generated/traces
-----
-====
-
-.Read a CTF trace as fast as possible using a dummy output.
-====
-[role="term"]
-----
-$ babeltrace my-trace --output-format=dummy
-----
-====
-
-.Read three CTF traces in stream intersection mode, add debugging information, and pretty-print them to a file.
-====
-[role="term"]
-----
-$ babeltrace trace1 trace2 trace3 --stream-intersection \
- --debug-info --output=pretty-out
-----
-====
-
-.Pretty-print a CTF trace and traces from an explicit source component, with the event times showed in seconds since Epoch.
-====
-[role="term"]
-----
-$ babeltrace ctf-trace --component=src.my-plugin.my-src \
- --params=output-some-event-type=yes --clock-seconds
-----
-====
-
-.Send LTTng live events to an explicit sink component.
-====
-[role="term"]
-----
-$ babeltrace --input-format=lttng-live \
- net://localhost/host/myhostname/mysession \
- --component=sink.my-plugin.my-sink
-----
-====
-
-.Trim a CTF trace, add debugging information, apply an explicit filter component, and write as a CTF trace.
-====
-[role="term"]
-----
-$ babeltrace /path/to/trace --timerange=22:14:38,22:15:07 \
- --debug-info --component=filter.my-plugin.my-filter \
- --params=criteria=xyz,ignore-abc=yes \
- --output-format=ctf --output=out-trace
-----
-====
-
-.Print the metadata text of a CTF trace.
-====
-[role="term"]
-----
-$ babeltrace /path/to/trace --output-format=ctf-metadata
-----
-====
-
-.Print the available LTTng live sessions of an LTTng relay daemon.
-====
-[role="term"]
-----
-$ babeltrace --input-format=lttng-live net://localhost
-----
-====
-
-
-include::common-cli-env.txt[]
-
-include::common-cli-files.txt[]
-
-include::common-cmd-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace(1),
-man:babeltrace-run(1),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-filter.lttng-utils.debug-info(7)
-===========================================
-:manpagetype: component class
-:revdate: 5 October 2017
-:comp: compcls:filter.lttng-utils.debug-info
-:defdebuginfoname: `debug_info`
-
-
-NAME
-----
-babeltrace-filter.lttng-utils.debug-info - Babeltrace's debugging
-information filter component class for LTTng traces
-
-
-DESCRIPTION
------------
-The Babeltrace {comp} component class, provided by the the
-man:babeltrace-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.
-+
-Example: `my-program@0x401040`.
-
-[[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.
-+
-Example: `load_user_config+0x194`.
-
-[[field-src]]`src` (string field)::
- Source file path or name followed by `: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.
-
-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.
-
-
-Compile an executable for debugging information analysis
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-With GCC or Clang, you should 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
-function.
-
-NOTE: This component class only supports the debugging information in
-DWARF format, version{nbsp}2 or later. Use the nlopt:-gdwarf or
-nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler
-options to explicitly generate DWARF debugging information.
-
-If you don't compile the executable's source files with the nlopt:-g
-option or with an equivalent option, no DWARF information is available:
-the component uses ELF symbols from the executable file instead. In this
-case, the events that the component creates do not contain the source
-file and line number (<<field-src,`src` field>>), but only the name of
-the nearest function symbol with an offset in bytes to the location in
-the executable from which the LTTng event occured (<<field-func,`func`
-field>>).
-
-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.
-
-
-LTTng prerequisites
-~~~~~~~~~~~~~~~~~~~
-A {comp} component can only analyze user space events generated by
-http://lttng.org[LTTng]{nbsp}2.8.0 or later.
-
-To get debugging information for LTTng-UST events which occur in
-executables and libraries which the system's loader loads (what
-you can see with man:ldd(1)):
-
-. Add the `ip` and `vpid` context fields to user space event records:
-+
---
-[role="term"]
-----
-$ lttng add-context --userspace --type=ip --type=vpid
-----
---
-+
-See man:lttng-add-context(1) for more details.
-
-. Enable the LTTng-UST state dump events:
-+
---
-[role="term"]
-----
-$ lttng enable-event --userspace 'lttng_ust_statedump:*'
-----
---
-+
-See man:lttng-enable-event(1) and man:lttng-ust(3) for more details.
-
-To get debugging information for LTTng-UST events which occur in
-dynamically loaded objects, for example plugins:
-
-. Do the previous steps (add context fields and enable
- the LTTng-UST state dump events).
-
-. Enable the LTTng-UST dynamic linker tracing helper events:
-+
---
-[role="term"]
-----
-$ lttng enable-event --userspace 'lttng_ust_dl:*'
-----
---
-+
-See man:lttng-ust-dl(3) for more details.
-
-. When you are ready to trace, start your application with the
- `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`:
-+
---
-[role="term"]
-----
-$ 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.
-
-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.
-
-The debugging information lookup order is the same as GDB's, namely:
-
-. Within the executable file itself.
-
-. Through the build ID method in the `/usr/lib/debug/.build-id`
- directory.
-
-. In the various possible debug link locations.
-
-The component uses the first debugging information file that it finds.
-
-You can use the param:deubg-info-dir initialization parameter to
-override the default `/usr/lib/debug` directory used in the build ID and
-debug link methods.
-
-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.
-
-If the trace was recorded on a separate machine, however, you can use
-the param:target-prefix parameter to specify a prefix directory, that
-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`.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
-
-param:debug-info-dir='DIR' (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:full-path=`yes` (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)::
- 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.
-
-
-Output
-~~~~~~
-`out`::
- Single output port to which the component sends the augmented
- or unaltered notifications.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-`BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-lttng-utils(7),
-man:lttng(1),
-man:lttng-add-context(1),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-filter.utils.muxer(7)
-================================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-filter.utils.muxer - Babeltrace's notification multiplexer
-filter component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:filter.utils.muxer component class, provided by
-the man:babeltrace-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 component does not alter the notifications
-it receives: it only sorts them.
-
-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.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
-
-param:assume-absolute-clock-classes=`yes` (boolean)::
- Assume that all clock classes are absolute.
-
-
-PORTS
------
-Input
-~~~~~
-`inN`, where `N` is a decimal integer starting at 0::
- Input port from which the component receives notifications to
- multiplex.
-+
-When you create the component, 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.
-+
-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.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-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:babeltrace(1):--log-level option of
- man:babeltrace(1).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-utils(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-filter.utils.trimmer(7)
-==================================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-filter.utils.trimmer - Babeltrace's trimmer filter
-component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:filter.utils.trimmer component class, provided by
-the man:babeltrace-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.
-
-
-[[time-param-fmt]]
-Time parameter format
-~~~~~~~~~~~~~~~~~~~~~
-The format of the param:begin and param:end parameters is:
-
-[verse]
-$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
-
-'YYYY'::
- 4-digit year.
-
-'MM'::
- 2-digit month (January is `01`).
-
-'DD'::
- 2-digit day.
-
-'hh'::
- 2-digit hour (24-hour format).
-
-'mm'::
- 2-digit minute.
-
-'ss'::
- 2-digit second.
-
-'nnnnnnnnn'::
- 9-digit nanosecond.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-You must specify at least one of the param:begin and param:end
-parameters.
-
-param:begin='BEGIN' (string or integer)::
- Set the trimmer's beginning time to 'BEGIN'.
-+
-If 'BEGIN' is a string, see <<time-param-fmt,Time parameter format>> for
-its format. If 'BEGIN' is an integer, it is the number of nanoseconds
-since Epoch.
-+
-If 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.
-
-param:end='END' (string or integer)::
- Set the trimmer's end time to 'END'.
-+
-If 'END' is a string, see <<time-param-fmt,Time parameter format>> for
-its format. If 'END' is an integer, it is the number of nanoseconds
-since Epoch.
-+
-If you don't specify this parameter, the component discards no events
-from the beginning of the trimming range.
-
-
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications.
-
-
-Output
-~~~~~~
-`out`::
- Single output port to which the components sends the notifications
- of which the time is in the trimming range.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-`BABELTRACE_FLT_UTILS_TRIMMER_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-utils(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-help(1)
-==================
-:manpagetype: command
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-help - Get help for a Babeltrace plugin or component class
-
-
-SYNOPSIS
---------
-[verse]
-*babeltrace help* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
- ('PLUGIN' | 'TYPE.PLUGIN.COMPCLS')
-
-
-DESCRIPTION
------------
-The `help` command prints the details and help text of either the plugin
-'PLUGIN' or the specific component class 'TYPE.PLUGIN.COMPCLS'.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-The available values for 'TYPE' are:
-
-`source` or `src`::
- Source component class.
-
-`filter` or `flt`::
- Filter component class.
-
-`sink`::
- Sink component class.
-
-See <<examples,EXAMPLES>> for usage examples.
-
-
-include::common-cmd-plugin-path.txt[]
-
-
-OPTIONS
--------
-include::common-gen-options.txt[]
-
-include::common-plugin-path-options.txt[]
-
-include::common-cmd-info-options.txt[]
-
-
-[[examples]]
-EXAMPLES
---------
-.Get help for a plugin and all its component classes.
-====
-[role="term"]
-----
-$ babeltrace help my-plugin
-----
-====
-
-.Get help for a specific plugin's source component class.
-====
-[role="term"]
-----
-$ babeltrace help src.my-plugin.my-source
-----
-====
-
-.Get help for a specific plugin's sink component class.
-====
-[role="term"]
-----
-$ babeltrace help sink.my-plugin.my-sink
-----
-====
-
-
-include::common-cli-env.txt[]
-
-include::common-cli-files.txt[]
-
-include::common-cmd-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace(1),
-man:babeltrace-list-plugins(1)
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-intro(7)
-===================
-:manpagetype: man page
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-intro - Introduction to Babeltrace
-
-
-DESCRIPTION
------------
-This man page is an introduction to the Babeltrace project.
-
-The <<what-is,WHAT IS BABELTRACE?>> section lists the parts of the
-project and shows the major changes from Babeltrace{nbsp}1 to
-Babeltrace{nbsp}2 while the <<concepts,BABELTRACE CONCEPTS>> section
-defines the core concepts of Babeltrace.
-
-The <<graph-repr,TRACE PROCESSING GRAPH REPRESENTATION>> section shows
-how some <<concepts,concepts>> are visually represented in other
-Babeltrace man pages.
-
-
-[[what-is]]
-WHAT IS BABELTRACE?
--------------------
-Babeltrace 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:
-
-[[libbabeltrace]]Babeltrace library (libbabeltrace)::
- A shared library with a C API.
-+
-With libbabeltrace, you can programmatically create <<plugin,plugins>>
-and <<comp-cls,component classes>>, build and run <<graph,processing
-graphs>>, and more (see the <<concepts,BABELTRACE CONCEPTS>> section for
-more details about those concepts). All the other Babeltrace parts rely
-on this library.
-
-[[babeltrace-1]]`babeltrace` command::
- A command-line interface which uses libbabeltrace to load plugins,
- create a trace processing graph, create components, and run the
- graph.
-+
-You can also use `babeltrace` to list the available plugins or to query
-an object from a component class.
-+
-See man:babeltrace(1).
-
-[[python-bindings]]Babeltrace Python bindings::
- A Python{nbsp}3 package which offers a Pythonic interface of
- libbabeltrace.
-+
-You can perform the same operations which are available in libbabeltrace
-with the Python bindings, but in a really easier way and with less code.
-
-Babeltrace project's plugins::
- The Babeltrace <<plugin,plugins>> shipped with the project.
-+
-Those plugins are not special, in that they only rely on libbabeltrace
-and you don't need them to use libbabeltrace, man:babeltrace(1), or the
-Python bindings.
-+
-The Babeltrace project's plugins are:
-+
---
-`ctf`::
- Common Trace Format input/output, including the LTTng live source.
-+
-See man:babeltrace-plugin-ctf(7).
-
-`lttng-utils`::
- Graph utilities specific to http://lttng.org/[LTTng] traces.
-+
-See man:babeltrace-plugin-lttng-utils(7).
-
-`text`::
- Text input/output.
-+
-See man:babeltrace-plugin-text(7).
-
-`utils`::
- Graph utilities (muxer, trimmer, counter, dummy sink).
-+
-See man:babeltrace-plugin-utils(7).
---
-
-Python plugin provider::
- A shared library which libbabeltrace 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{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.
-
-Babeltrace{nbsp}1 exists since 2010. The major improvements brought by
-Babeltrace{nbsp}2 are:
-
-* Full plugin support: any user can distribute a Babeltrace plugin and,
- as long as <<libbabeltrace,libbabeltrace>> finds it, any application
- linked to libbabeltrace can load it and use it.
-+
-Plugins are not just input and output formats: they provide source,
-filter, and sink <<comp-cls,component classes>> so that you can connect
-specialized, reusable components together in a graph to create a
-customized trace conversion or analysis device.
-
-* In order to support user components, all the objects of libbabeltrace
- 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.
-
-* All the parts of the Babeltrace 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
-<<libbabeltrace,libbabeltrace>> and its <<python-bindings,Python
-bindings>>, but also as command-line actions and options in the
-<<babeltrace-1,`babeltrace` command>>. The other Babeltrace man 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.
-
-[[comp-cls]]Component class::
- A reusable class from which you can instantiate one or more
- <<comp,component>> instances.
-+
-There are three types of component classes used to instantiate the three
-types of components (source, filter, and sink).
-+
-A component class provides 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.
-
-[[comp]]Component::
- A node within a <<graph,trace processing graph>>.
-+
-There are three types of components:
-+
---
-Source component::
- An input component which produces <<notif,notifications>>.
-+
-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.
-+
-Examples: filter which removes notifications based on an expression,
-filter which adds debugging information to selected events, notification
-multiplexer, trace trimmer.
-
-Sink component::
- An output component which consumes notifications and usually writes
- them to one or more formatted files.
-+
-Examples: log file output, CTF files output, text output on the
-console.
---
-+
-Components are connected together within a <<graph,trace processing
-graph>> through their <<port,ports>>. Source components have output
-ports, sink components have input ports, and filter components have
-both.
-+
-A component is the instance of a <<comp-cls,component class>>. The terms
-_component_ and _component 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.
-
-[[port]]Port::
- A connection point, on a <<comp,component>>, from which are sent or
- to which are received <<notif,notifications>> when the <<graph,trace
- processing graph>> is running.
-+
-An output port is where notifications are sent. An input port is where
-notifications 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.
-+
-A filter or sink component receiving notifications from its input ports
-is said to _consume_ notifications.
-+
-The link between an output port and input port is a <<conn,connection>>.
-+
-A component can dynamically add and remove ports while a graph is
-running. For example, a compcls:filter.utils.muxer component always
-makes sure that it has at least one available input port.
-
-[[conn]]Connection::
- The link between an output <<port,port>> and an input port through
- which <<notif,notifications>> flow when a <<graph,trace processing
- graph>> is running.
-
-[[notif]]Notification::
- An atomic element sent from an output <<port,port>> to an
- input port.
-+
-A source <<comp,component>> produces notifications, while a sink
-component consumes them. A filter component can both consume and
-produce notifications.
-+
-The main types of notifications are:
-+
---
-Event::
- A trace event record within a packet.
-
-Packet beginning::
- The beginning of a packet within a stream.
-+
-A packet is a container of events.
-
-Packet end::
- The end of a packet within a stream.
-
-Stream beginning::
- The beginning of a stream.
-+
-A stream is a container of packets.
-+
-Usually, a given source component's output port sends packet and
-event notifications which belong to a single stream.
-
-Stream end::
- The end of a stream.
-
-Discarded events::
- A count of discarded events within a given time interval for a given
- stream.
-
-Discarded packets::
- A count of discarded packets within a given time interval for a
- given stream.
---
-
-[[graph]]Trace processing graph::
- A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where
- nodes are <<comp,components>> and <<notif,notifications>> flow from
- output <<port,ports>> to input ports.
-+
-You can build a trace processing graph with
-<<libbabeltrace,libbabeltrace>>, with the <<python-bindings,Babeltrace
-Python bindings>>, or with the man:babeltrace-run(1) and
-man:babeltrace-convert(1) 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.
-
-[[plugin]]Plugin::
- A container of <<comp-cls,component classes>> as a shared library.
-+
-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.
-+
-<<libbabeltrace,libbabeltrace>> can load a plugin (`.so` or `.dll` file)
-at run time: the result is a plugin object in which you can find a
-specific component class and instantiate it within a <<graph,trace
-processing graph>> as a <<comp,component>>.
-+
-The <<babeltrace-1,`babeltrace` command>> uses the
-'TYPE.PLUGIN.COMPCLS' format to identify a specific component
-class within a specific plugin. 'TYPE' is either `source`, `filter`,
-or `sink`.
-+
-You can list the available Babeltrace plugins with the
-man:babeltrace-list-plugins(1) command.
-
-[[query]]Query::
- An operation with which you can get a named object from a
- <<comp-cls,component class>>, possibly with the help of query
- parameters.
-+
-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.
-+
-You can use the man:babeltrace-query(1) command to query a component
-class's object.
-
-
-[[graph-repr]]
-TRACE PROCESSING GRAPH REPRESENTATION
--------------------------------------
-In the Babeltrace man pages, a component is represented with a box. The
-box has the <<comp-cls,component class>> type, <<plugin,plugin>> name,
-and component class name at the top. Just below, between square
-brackets, is its component instance name within the <<graph,trace
-processing graph>>. Each <<port,port>> is represented with an `@` symbol
-on the edge of the component box with its name inside the box. Output
-ports are on the right edge while input ports are on the left edge.
-
-For example, here's a source component box:
-
-----
-+------------+
-| src.ctf.fs |
-| [my-src] |
-| |
-| stream0 @
-| stream1 @
-| stream2 @
-+------------+
-----
-
-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`.
-
-A trace processing graph is represented with multiple component boxes
-connected together. The <<conn,connections>> are arrows from output
-ports to input ports.
-
-For example, here's a simple conversion graph:
-
-----
-+------------+ +-----------------+ +------------------+
-| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
-| [ctf] | | [muxer] | | [text] |
-| | | | | |
-| stream0 @--->@ in0 out @--->@ in |
-| stream1 @--->@ in1 | +------------------+
-| stream2 @--->@ in2 |
-+------------+ @ in3 |
- +-----------------+
-----
-
-Note that input port `in3` of component `muxer` is not currently
-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:
-
-----
- CTF trace
- |
-.------'
-| +------------+ +-----------------+ +------------------+
-| | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
-'->| [ctf] | | [muxer] | | [text] |
- | | | | | |
- | stream0 @--->@ in0 out @--->@ in |
- | stream1 @--->@ in1 | +--+---------------+
- | stream2 @--->@ in2 | |
- +------------+ @ in3 | '---> Console
- +-----------------+
-----
-
-Here's another example of a more complex graph which splits a specific
-stream using some criteria:
-
-----
-+------------+ +-----------------+ +------------------+
-| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
-| [ctf-in] | | [muxer] | | [text] |
-| | | | | |
-| stream0 @--->@ in0 out @--->@ in |
-| stream1 @--->@ in1 | +------------------+
-| stream2 @-. @ in2 |
-+------------+ | +-----------------+ +-------------+
- | | sink.ctf.fs |
- | | [ctf-out0] |
- | +-------------------+ | |
- | | flt.some.splitter | .->@ in |
- | | [splitter] | | +-------------+
- | | | |
- '->@ in A @-' +-------------+
- | B @-. | sink.ctf.fs |
- +-------------------+ | | [ctf-out1] |
- | | |
- '->@ in |
- +-------------+
-----
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace(1)
+++ /dev/null
-babeltrace-list-plugins(1)
-==========================
-:manpagetype: command
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-list-plugins - List Babeltrace plugins and their properties
-
-
-SYNOPSIS
---------
-[verse]
-*babeltrace list-plugins* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
- [opt:--omit-system-plugin-path]
- [opt:--plugin-path='PATH'[:__PATH__]...]
-
-
-DESCRIPTION
------------
-The `list-plugins` command prints a list of available Babeltrace
-plugins along with their component classes and their properties.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-
-include::common-cmd-plugin-path.txt[]
-
-
-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
---------
-man:babeltrace(1),
-man:babeltrace-help(1),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-log(1)
-=================
-:manpagetype: program
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-log - Convert a Linux kernel ring buffer to a CTF trace
-
-
-SYNOPSIS
---------
-[verse]
-*babeltrace-log* [opt:--with-timestamps] 'OUTPUT-PATH'
-
-
-DESCRIPTION
------------
-The `babeltrace-log` tool reads the lines of a Linux kernel ring buffer,
-as printed by the man:dmesg(1) tool, from the standard input stream and
-converts them to a http://diamon.org/ctf/[CTF] trace written to the
-'OUTPUT-PATH' directory.
-
-Usage example:
-
-[role="term"]
-----
-$ dmesg | babeltrace-log --with-timestamps my-trace
-----
-
-The events of the generated CTF trace are named `string` and contain a
-single payload string field named `str` which contains the corresponding
-ring buffer line.
-
-By default, `babeltrace-log` does not try to extract the timestamps of
-the kernel ring buffer lines to 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 a timestamp which
-could be extracted. You can make `babeltrace-log` extract timestamps
-from lines with the opt:--with-timestamps option.
-
-
-OPTIONS
--------
-opt:-t, opt:--with-timestamps::
- Extract timestamps from the kernel ring buffer lines: set
- the created event's payload's `str` field to the rest of the line,
- excluding any timestamp prefix.
-
-
-ENVIRONMENT VARIABLES
----------------------
-See the environment variables of man:babeltrace-source.text.dmesg(7),
-man:babeltrace-filter.utils.muxer(7), and
-man:babeltrace-sink.ctf.fs(7).
-
-include::common-lib-env.txt[]
-
-include::common-cli-files.txt[]
-
-include::common-cmd-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-intro(7),
-man:babeltrace-source.text.dmesg(7),
-man:babeltrace-filter.utils.muxer(7),
-man:babeltrace-sink.ctf.fs(7)
+++ /dev/null
-babeltrace-plugin-ctf(7)
-========================
-:manpagetype: plugin
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-plugin-ctf - Babeltrace'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:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-
-COMPONENT CLASSES
------------------
-compcls:sink.ctf.fs::
- Writes the received notifications as a CTF trace on the file system.
-+
-See man:babeltrace-sink.ctf.fs(7).
-
-compcls:source.ctf.fs::
- Opens one or more CTF traces on the file system and emits the
- notifications of their data stream files.
-+
-See man:babeltrace-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.
-+
-See man:babeltrace-source.ctf.lttng-live(7).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-sink.ctf.fs(7),
-man:babeltrace-source.ctf.fs(7),
-man:babeltrace-source.ctf.lttng-live(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-plugin-lttng-utils(7)
-================================
-:manpagetype: plugin
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-plugin-lttng-utils - Babeltrace'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
-compcls:source.ctf.lttng-live components to read LTTng traces (see
-man:babeltrace-plugin-ctf(7)).
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-
-COMPONENT CLASSES
------------------
-compcls:filter.lttng-utils.debug-info::
- Receives notifications from its input port and creates new,
- equivalent notifications with additionnal debugging information.
-+
-See man:babeltrace-filter.lttng-utils.debug-info(7).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-filter.lttng-utils.debug-info(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-plugin-text(7)
-=========================
-:manpagetype: plugin
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-plugin-text - Babeltrace's plain text plugin
-
-
-DESCRIPTION
------------
-The Babeltrace `text` plugin contains component classes which read or
-write plain text data.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-
-COMPONENT CLASSES
------------------
-compcls:sink.text.pretty::
- Pretty-prints the notifications it receives to the console or to a
- file.
-+
-See man:babeltrace-sink.text.pretty(7).
-
-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.
-+
-See man:babeltrace-source.text.dmesg(7).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-sink-text.text(7),
-man:babeltrace-source-text.dmesg(7),
-man:babeltrace-intro(7),
+++ /dev/null
-babeltrace-plugin-utils(7)
-==========================
-:manpagetype: plugin
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-plugin-utils - Babeltrace's utilities plugin
-
-
-DESCRIPTION
------------
-The Babeltrace `utils` plugin contains common, generic utility component
-classes which you can use in any processing graph.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-
-COMPONENT CLASSES
------------------
-compcls:filter.utils.muxer::
- Multiplexes the notifications received on its multiple input ports
- by time to its single output port.
-+
-See man:babeltrace-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.
-+
-See man:babeltrace-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:babeltrace(1).
-+
-See man:babeltrace-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.
-+
-See man:babeltrace-sink.utils.counter(7).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-intro(7),
-man:babeltrace-filter.utils.muxer(7),
-man:babeltrace-filter.utils.trimmer(7),
-man:babeltrace-sink.utils.counter(7),
-man:babeltrace-sink.utils.dummy(7)
+++ /dev/null
-babeltrace-query(1)
-===================
-:manpagetype: command
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-query - Query object from a component class
-
-
-SYNOPSIS
---------
-[verse]
-*babeltrace 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'
-
-
-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.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-The available values for 'TYPE' are:
-
-`source`::
-`src`::
- Source component class.
-
-`filter`::
-`flt`::
- Filter component class.
-
-`sink`::
- Sink component class.
-
-The exact object names and the parameters that a given component class
-expects are described in its documentation. man:babeltrace-help(1) can
-generally provide this information.
-
-You can use the opt:--params='PARAMS' option to pass parameters to the
-component class's query function. See <<params-fmt,Parameters format>>
-for the exact format of 'PARAMS'.
-
-The output of the `query` command looks like YAML, although it is not
-guaranteed that it is YAML-compliant.
-
-See <<examples,EXAMPLES>> for usage examples.
-
-
-include::common-cmd-params-format.txt[]
-
-include::common-cmd-plugin-path.txt[]
-
-
-OPTIONS
--------
-include::common-gen-options.txt[]
-
-
-Query parameters
-~~~~~~~~~~~~~~~~
-opt:-p 'PARAMS', opt:--params='PARAMS'::
- Set the query parameters to 'PARAMS'. See <<params-fmt,Parameters
- format>> for the exact format of 'PARAMS'.
-
-
-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.
-====
-[role="term"]
-----
-$ babeltrace query src.ctf.lttng-live sessions \
- --params='url="net://RHOST/host/TGTHOST"'
-----
-====
-
-.Query the metadata info (includes the decoded text) of a CTF trace located on the local file system.
-====
-[role="term"]
-----
-$ babeltrace query src.ctf.fs metadata-info \
- --params='path="/path/to/trace"'
-----
-====
-
-.Query the trace info of CTF traces located on the local file system.
-====
-[role="term"]
-----
-$ babeltrace query src.ctf.fs trace-info \
- --params='path="/path/to/trace"'
-----
-====
-
-.Query some object from a sink component class without parameters.
-====
-[role="term"]
-----
-$ babeltrace 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:babeltrace(1),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-run(1)
-=================
-:manpagetype: command
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-run - Create a trace processing graph and run it
-
-
-SYNOPSIS
---------
-[verse]
-*babeltrace 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'
-
-
-DESCRIPTION
------------
-The `run` command creates a trace processing graph and runs it.
-
-See man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-The `run` command uses libbabeltrace to dynamically load plugins which
-supply component classes. With the `run` command, you specify which
-component classes to instantiate as components and how they must be
-connected.
-
-The steps to write a `babeltrace run` command line are:
-
-. Specify which component classes to instantiate as components and
- how. This is the 'COMPONENTS' part of the synopsis. See
- <<create-comps,Create components>> to learn more.
-
-. Specify how to connect component instances together with one or more
- opt:--connect options. See <<connect-comps,Connect components>> to
- learn more.
-
-NOTE: The man:babeltrace-convert(1) command is a specialization of the
-`run` command for the very common case of converting one or more traces:
-it generates a `run` command line and executes it. You can use its
-manopt:babeltrace-convert(1):--run-args or
-manopt:babeltrace-convert(1):--run-args-0 option to make it print the
-equivalent `run` command line instead.
-
-
-[[create-comps]]
-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 type of the component class to instantiate: source, filter, or
- sink.
-
-* The name of the plugin in which to find the component class to
- instantiate.
-
-* The name of the component class to instantiate.
-
-You can use the opt:--component option multiple times to create
-multiple components. You can instantiate the same component class
-multiple times as different component instances.
-
-At any point in the command line, the opt:--base-params sets the current
-base initialization parameters and the opt:--reset-base-params resets
-them. When you specify a opt:--component option, its initial
-initialization parameters are a copy of the current base initialization
-parameters.
-
-Immediately following a opt:--component option on the command line, the
-created component is known as the _current component_ (until the next
-opt:--component option).
-
-The following, optional command-line options apply to the current
-component:
-
-opt:--name='NAME'::
- Set the name of the current component to 'NAME'.
-
-opt:--params='PARAMS'::
- Add 'PARAMS' to the initialization parameters of the current
- component. If 'PARAMS' contains a key which exists in the current
- component's initialization parameters, this parameter is replaced.
-+
-See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
-
-
-[[connect-comps]]
-Connect components
-~~~~~~~~~~~~~~~~~~
-The components which you create from component classes with the
-opt:--component option (see <<create-comps,Create components>>) can
-create input and output _ports_ depending on their type. An output port
-is where notifications, like trace events, are sent. An input port is
-where notifications are received. For a given component instance, each
-port has a unique name.
-
-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.
-
-The format of a connection rule (the argument of the opt:--connect
-option) is:
-
-[verse]
-__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
-
-'UP-COMP-PATH'::
- Upstream component name pattern.
-
-'UP-PORT-PAT'::
- Upstream port name pattern.
-
-'DOWN-COMP-PATH'::
- Downstream component name pattern.
-
-'DOWN-PORT-PAT'::
- Downstream 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:
- 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.
-----
-
-__UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
-__DOWN-PORT-PAT__ are globbing patterns where only the wildcard
-character, `*`, is special: it matches zero or more characters. You must
-escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:.
-
-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:
-
-----
---connect='A.out*:B.in*' --connect=A:B --connect='*:C'
-----
-
-With those connection rules:
-
-* 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`.
-
-* Any other output port of component `A` is connected 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`.
-
-The `run` command fails when it cannot find an input port to which to
-connect a created output port using the provided connection
-rules.
-
-See <<examples,EXAMPLES>> for more examples.
-
-
-include::common-cmd-params-format.txt[]
-
-include::common-cmd-plugin-path.txt[]
-
-
-OPTIONS
--------
-include::common-gen-options.txt[]
-
-
-Component creation
-~~~~~~~~~~~~~~~~~~
-opt:-b 'PARAMS', opt:--base-params='PARAMS'::
- Set the current base parameters to 'PARAMS'. You can reset the
- current base parameters with the opt:--reset-base-params option.
- See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
-
-opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
- Create a component initially named 'NAME' (if specified) from the
- component class of type 'TYPE' named 'COMPCLS' found in the plugin
- named 'PLUGIN', and set it as the current component.
-+
-The available values for 'TYPE' are:
-+
---
-`source`::
-`src`::
- Source component class.
-
-`filter`::
-`flt`::
- Filter component class.
-
-`sink`::
- Sink component class.
---
-+
-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:-p 'PARAMS', opt:--params='PARAMS'::
- Add 'PARAMS' to the initialization parameters of the current
- component. If 'PARAMS' contains a key which exists in the current
- component's initialization parameters, replace the parameter.
- See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
-
-opt:-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'. See
- <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
-
-
-Graph configuration
-~~~~~~~~~~~~~~~~~~~
-opt:--retry-duration='DURUS'::
- Set the duration of a single retry to 'DURUS'{nbsp}µs when a
- component reports "try again later" (busy network or file system,
- for example).
-+
-Default: 100000 (100{nbsp}ms).
-
-
-include::common-plugin-path-options.txt[]
-
-include::common-cmd-info-options.txt[]
-
-
-[[examples]]
-EXAMPLES
---------
-.Create a single-port source component and a single-port sink component and connect them.
-====
-[role="term"]
-----
-$ babeltrace run --component=A:src.plug.my-src \
- --component=B:sink.plug.my-sink \
- --connect=A:B
-----
-
-Possible resulting graph:
-
-----
-+-----------------+ +-------------------+
-| src.plug.my-src | | sink.plug.my-sink |
-| [A] | | [B] |
-| | | |
-| out @--->@ in |
-+-----------------+ +-------------------+
-----
-====
-
-.Use the opt:--name option to name the current component.
-====
-[role="term"]
-----
-$ babeltrace 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
-`the-source`.
-
-[role="term"]
-----
-$ babeltrace 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
-----
-====
-
-.Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters.
-====
-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`
-
-[role="term"]
-----
-$ babeltrace 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
-----
-====
-
-.Specify a component connection fallback rule.
-====
-In this example, any `A` output port of which the name starts with
-`foo` is connected to a `B` input port of which the name starts with
-`nin`. Any other `A` output port is connected to a `B` input port of
-which the name starts with `oth`.
-
-The order of the opt:--connect options is important here: the opposite
-order would create a system in which the first rule is always satisfied,
-and _any_ `A` output port, whatever its name, would be connected to a
-`B` input port with a name that starts with `oth`.
-
-[role="term"]
-----
-$ babeltrace run --component=A:src.plug.my-src \
- --component=B:sink.plug.my-sink \
- --connect='A.foo*:B:nin*' --connect='A:B.oth*'
-----
-
-Possible resulting graph:
-
-----
-+-----------------+ +-------------------+
-| src.plug.my-src | | sink.plug.my-sink |
-| [A] | | [B] |
-| | | |
-| foot @--->@ nine |
-| foodies @--->@ ninja |
-| some-port @--->@ othello |
-| hello @--->@ other |
-+-----------------+ +-------------------+
-----
-====
-
-
-include::common-cli-env.txt[]
-
-include::common-cli-files.txt[]
-
-include::common-cmd-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace(1),
-man:babeltrace-convert(1),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-sink.ctf.fs(7)
-=========================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-sink.ctf.fs - Babeltrace's file system CTF sink component
-class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:sink.ctf.fs component class, provided by the
-man:babeltrace-plugin-ctf(7) plugin, once instantiated, writes the
-events it receives to one or more http://diamon.org/ctf/[CTF] 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.
-
-This component guarantees that the output traces are semantically
-equivalent to the input traces. This means that a given output CTF trace
-contains:
-
-* 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.
-
-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.
-
-
-Output path
-~~~~~~~~~~~
-The path of a CTF trace is the directory which directly contains the
-metadata and data stream files as children.
-
-The rules to determine the path of a generated CTF trace are:
-
-* If the param:single-trace parameter is true, use the value of the
- param:path parameter.
-+
-Otherwise:
-+
---
-* 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.
-+
-Otherwise, use `OUTPUTPATH/trace[SUFFIX]`, where `OUTPUTPATH` and
-`SUFFIX` are defined above.
---
-
-
-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.
-
-param:single-trace=`yes` (boolean, optional)::
- Assume that the component only receives notifications related to
- a single source trace.
-
-
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-ctf-plugin-env.txt[]
-
-
-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:babeltrace(1):--log-level option of
- man:babeltrace(1).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-ctf(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-sink.text.pretty(7)
-==============================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-sink.text.pretty - Babeltrace's pretty-printing sink
-component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:sink.text.pretty component class, provided by the
-man:babeltrace-plugin-text(7) plugin, once instantiated, pretty-prints
-the events it receives from its input port to the console or to a file.
-
-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 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 for human
-consumption. You can use the param:color parameter to force the color
-support or to disable it.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
-
-param:clock-cycles=`yes` (boolean)::
- Print event times in clock cycles instead of hours, minutes,
- seconds, and nanoseconds.
-
-param:clock-date=`yes` (boolean)::
- Print event times _and_ dates.
-
-param:clock-gmt=`yes` (boolean)::
- Print event times in the GMT time zone instead of the local time
- zone.
-
-param:clock-seconds=`yes` (boolean)::
- Print event times in seconds instead of hours, minutes,
- seconds, and nanoseconds.
-
-param:color=(`never` | `auto` | `always`) (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:field-default=(`show` | `hide`) (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)::
- Show or hide the event's Eclipse Modeling Framework URI field.
-
-param:field-loglevel=(`yes` | `no`) (boolean)::
- Show or hide the event's logging level field.
-
-param:field-trace=(`yes` | `no`) (boolean)::
- Show or hide the trace name field.
-
-param:field-trace:domain=(`yes` | `no`) (boolean)::
- Show or hide the tracing domain field.
-
-param:field-trace:hostname=(`yes` | `no`) (boolean)::
- Show or hide the hostname field.
-
-param:field-trace:procname=(`yes` | `no`) (boolean)::
- Show or hide the process name field.
-
-param:field-trace:vpid=(`yes` | `no`) (boolean)::
- Show or hide the virtual process ID field.
-
-param:name-context=(`yes` | `no`) (boolean)::
- Show or hide the field names in the context scopes.
-
-param:name-default=(`show` | `hide`) (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)::
- Show or hide the field names in the header scopes.
-
-param:name-payload=(`yes` | `no`) (boolean)::
- Show or hide the field names in the event payload scopes.
-
-param:name-scope=(`yes` | `no`) (boolean)::
- Show or hide the scope names.
-
-param:no-delta=`yes` (boolean)::
- Do not print the time delta between consecutive lines.
-
-param:path='PATH' (string)::
- Print the text output to the file 'PATH' instead of the standard
- output.
-
-param:verbose=`yes` (boolean)::
- Turn the verbose mode on.
-
-
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- event notifications to pretty-print.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-text(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-sink.utils.counter(7)
-================================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-sink.utils.counter - Babeltrace's notification counter sink
-component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:sink.utils.counter component class, provided by
-the man:babeltrace-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.
-
-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)
-----
-
-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.
-
-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.
-
-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.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
-
-param:hide-zero=`yes` (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.
-
-
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications to count.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-utils(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-sink.utils.dummy(7)
-==============================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-sink.utils.dummy - Babeltrace's dummy sink component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:sink.utils.dummy component class, provided by the
-man:babeltrace-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.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-This component class has no initialization parameters.
-
-
-PORTS
------
-Input
-~~~~~
-`in`::
- Single input port from which the component receives the
- notifications to discard.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-utils(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-source.ctf.fs(7)
-===========================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-source.ctf.fs - Babeltrace's file system CTF source
-component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:source.ctf.fs component class, provided by the
-man:babeltrace-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.
-
-
-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.
-
-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.
-
-The component skips the following files when looking for data stream
-files:
-
-* Any file which starts with `.`, including subdirectories.
-* Any non-regular file.
-
-
-[[trace-naming]]
-Trace naming
-~~~~~~~~~~~~
-A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`,
-with:
-
-`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.
-
-`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 `.`.
-
-For example, assume the following hierarchy:
-
-----
-/
- home/
- user/
- my-traces/
- trace1/
- metadata
- ...
- node-traces/
- server/
- metadata
- ...
- client/
- metadata
- ...
-----
-
-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`
-
-
-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.
-
-In particular:
-
-* 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`.
-
-* 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.
-
-* 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).
-
-
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional unless indicated otherwise.
-
-param:clock-class-offset-ns (integer)::
- Value to add, in 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.
-+
-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.
-
-
-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.
-
-
-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.
-
-Parameters:
-
-`path` (string, mandatory)::
- Path to the CTF trace directory which contains the `metadata` file.
-
-Returned object (map):
-
-`text` (string)::
- Plain text metadata.
-
-`is-packetized` (boolean)::
- True if the metadata stream is packetized.
-
-
-`trace-info`
-~~~~~~~~~~~~
-You can query the `trace-info` object for a set of CTF traces to get
-information about the data streams they contain, their intersection time
-range, and more.
-
-This query object requires that the processed CTF traces have the
-`timestamp_begin` and `timestamp_end` fields in their packet context
-field types.
-
-Parameters:
-
-`path` (string, mandatory)::
- Path to a directory to recurse to find CTF traces.
-
-Returned object (array of maps, one element for each found trace):
-
-`name` (string)::
- Trace name, as per the explanations in the <<trace-naming,Trace
- naming>> section.
-
-`path` (string)::
- Trace path.
-
-`range-ns` (map)::
- Full time range of the trace.
-+
---
-`begin` (integer)::
- Beginning time (ns since Epoch) of the trace.
-
-`end` (integer)::
- End time (ns since Epoch) of the trace.
---
-
-`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.
-
-`end` (integer)::
- End time (ns since Epoch) of the trace's data stream intersection.
---
-
-`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.
-
-`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.
-
-`end` (integer)::
- End time (ns since Epoch) of the data stream.
---
---
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-ctf-plugin-env.txt[]
-
-
-Component class
-~~~~~~~~~~~~~~~
-include::common-common-compat-env.txt[]
-
-`BABELTRACE_SRC_CTF_FS_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-ctf(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace-source.ctf.lttng-live(7)
-===================================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-source.ctf.lttng-live - Babeltrace's LTTng live source
-component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:source.ctf.lttng-live source component class,
-provided by the man:babeltrace-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].
-
-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.
-
-The component connects to an LTTng relay daemon using the param:url
-parameter.
-
-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.
-
-The component names each trace `[HOSTNAME/]SESSION/PATH`, with:
-
-`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.
-
-`SESSION`::
- Tracing session name.
-
-`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
-----
-
-For example:
-
-----
-myhost/auto-20150909-223909/ust/uid/1000/64-bit
-----
-
-A compcls:source.ctf.lttng-live never blocks: it asks the downstream
-component to try again later instead.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-param:url='URL' (string, mandatory)::
- The URL to use to connect to the LTTng relay daemon. The format
- of 'URL' is:
-+
---
-[verse]
-net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__
-
-'RDHOST'::
- 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.
-
-'TGTHOST'::
- Target's host name or IP address.
-
-'SESSION'::
- Name of the LTTng tracing session from which to receive data.
---
-
-
-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.
-
-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.
-
-
-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.
-
-Parameters:
-
-`url` (string, mandatory)::
- The URL to use to connect to the LTTng relay daemon. The format
- of 'URL' is:
-+
---
-[verse]
-net[4]://__RDHOST__[:__RDPORT__]
-
-'RDHOST'::
- 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.
---
-
-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.
-
-`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)::
- Current number of LTTng live clients connected to the relay daemon
- to receive data from this tracing session.
-
-
-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[]
-
-
-Component class
-~~~~~~~~~~~~~~~
-include::common-common-compat-env.txt[]
-
-`BABELTRACE_SRC_CTF_LTTNG_LIVE_LOG_LEVEL`::
- Component class's log level. The available values are the
- same as for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1).
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-ctf(7),
-man:babeltrace-intro(7),
-man:lttng-relayd(8),
-man:lttng-create(1)
+++ /dev/null
-babeltrace-source.text.dmesg(7)
-===============================
-:manpagetype: component class
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace-source.text.dmesg - Babeltrace's Linux kernel ring buffer
-source component class
-
-
-DESCRIPTION
------------
-The Babeltrace compcls:source.text.dmesg component class, provided by
-the man:babeltrace-plugin-text(7) plugin, once instantiated, 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.
-
-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.
-
-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.
-
-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:
-
-----
-[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.
-
-
-INITIALIZATION PARAMETERS
--------------------------
-The following parameters are optional.
-
-param:no-extract-timestamp=`yes` (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)::
- 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.
-
-
-QUERY OBJECTS
--------------
-This component class has no objects to query.
-
-
-ENVIRONMENT VARIABLES
----------------------
-include::common-common-compat-env.txt[]
-
-
-include::common-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-plugin-text(7),
-man:babeltrace-intro(7)
+++ /dev/null
-babeltrace(1)
-=============
-:manpagetype: program
-:revdate: 5 October 2017
-
-
-NAME
-----
-babeltrace - Convert or process one or more traces, and more
-
-
-SYNOPSIS
---------
-[verse]
-*babeltrace* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] ['<<commands,CMD>>'] ['CMD ARGS']
-
-
-DESCRIPTION
------------
-`babeltrace` 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 man:babeltrace-intro(7) to learn more about the Babeltrace
-project and its core concepts.
-
-Most of the `babeltrace` commands load Babeltrace plugins to perform
-their 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 specific command's
- nlopt:--plugin-path option.
-
-. `$HOME/.local/lib/babeltrace/plugins`
-
-. +{system_plugin_path}+
-
-You can use the man:babeltrace-list-plugins(1) command to dynamically
-list the available plugins and what they offer. See <<plugins,PLUGINS>>
-for a list of plugins shipped with Babeltrace.
-
-
-OPTIONS
--------
-opt:-d, opt:--debug::
- Turn the debugging mode on.
-+
-This is equivalent to opt:--log-level=`VERBOSE`.
-
-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`.
-+
-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
- `VERBOSE` level. This level should :not: be enabled in production.
-
-`VERBOSE`::
-`V`::
- Low-level debugging context information. This level should :not: be
- enabled in production.
---
-
-opt:-v, opt:--verbose::
- Turn the verbose mode on.
-+
-This is equivalent to opt:--log-level=`INFO`.
-
-opt:-h, opt:--help::
- Show help and quit.
-
-opt:-V, opt:--version::
- Show version and quit.
-
-
-[[commands]]
-COMMANDS
---------
-The following commands also have their own nlopt:--help option.
-
-man:babeltrace-convert(1)::
- Build a trace conversion graph and run it.
-+
-This is the default command: you don't need to explicitly
-specify this command name to use it.
-
-man:babeltrace-help(1)::
- Get help for a specific plugin or plugin's component class.
-
-man:babeltrace-list-plugins(1)::
- List the available Babeltrace plugins and their component classes.
-
-man:babeltrace-query(1)::
- Query an object from a component class.
-
-man:babeltrace-run(1)::
- Build a trace processing graph and run it.
-
-
-[[plugins]]
-PLUGINS
--------
-The following plugins are provided by the Babeltrace project itself:
-
-man:babeltrace-plugin-ctf(7)::
- CTF trace input (from the file system and from the LTTng-live
- protocol) and output to the file system.
-+
-* man:babeltrace-sink.ctf.fs(7)
-* man:babeltrace-source.ctf.fs(7)
-* man:babeltrace-source.ctf.lttng-live(7)
-
-ifeval::[{enable_debug_info} == 1]
-man:babeltrace-plugin-lttng-utils(7)::
- Processing graph utilities for LTTng traces.
-+
-* man:babeltrace-filter.lttng-utils.debug-info(7)
-endif::[]
-
-man:babeltrace-plugin-text(7)::
- Text input and output.
-+
-* man:babeltrace-sink.text.pretty(7)
-* man:babeltrace-source.text.dmesg(7)
-
-man:babeltrace-plugin-utils(7)::
- Processing graph utilities.
-+
-* man:babeltrace-filter.utils.muxer(7)
-* man:babeltrace-filter.utils.trimmer(7)
-* man:babeltrace-sink.utils.counter(7)
-* man:babeltrace-sink.utils.dummy(7)
-
-
-include::common-cli-env.txt[]
-
-include::common-cli-files.txt[]
-
-include::common-cmd-footer.txt[]
-
-
-SEE ALSO
---------
-man:babeltrace-convert(1),
-man:babeltrace-help(1),
-man:babeltrace-list-plugins(1),
-man:babeltrace-query(1),
-man:babeltrace-run(1),
-man:babeltrace-intro(7)
--- /dev/null
+babeltrace2-convert(1)
+=====================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-convert - Convert one or more traces
+
+
+SYNOPSIS
+--------
+Convert one or more traces:
+
+[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'
+
+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'
+
+Print the available http://lttng.org/docs/#doc-lttng-live[LTTng live]
+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'
+
+
+DESCRIPTION
+-----------
+The `convert` command creates a trace conversion graph and runs it.
+
+See man:babeltrace2-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+[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`:
+
+[role="term"]
+----
+$ babeltrace2 convert ...
+$ babeltrace2 ...
+----
+
+If you need to make sure that you are executing the `convert` command,
+use `babeltrace2 convert` explicitly.
+====
+
+A conversion graph is a specialized trace processing graph focused on
+the conversion of one or more traces to another format, possibly
+filtering their events and other notifications in the process. A
+conversion graph is a linear chain of components after the source
+streams are merged:
+
+----
++----------+
+| source 1 |-.
++----------+ |
+ | +-------+
++----------+ '->| | +---------+ +------------+
+| source 2 |--->| muxer |--->| trimmer |--->| debug-info |-.
++----------+ .->| | +---------+ +------------+ |
+ | +-------+ |
++----------+ | .----------------------------------------'
+| ... |-' | +---------------+ +------+
++----------+ '->| other filters |--->| sink |
+ +---------------+ +------+
+----
+
+Note that the trimmer, debugging information, and other filters are
+optional. See <<comp-create-impl,Create implicit components>> to learn
+how to enable them.
+
+If you need another processing graph layout, use the more flexible
+man:babeltrace2-run(1) command.
+
+Like with the man:babeltrace2-run(1) command, you can create components
+explicitly with the opt:--component option (see
+<<comp-create-expl,Create explicit components>>). You can also use one
+of the many specific `convert` command options and arguments to create
+implicit components from known component classes (see
+<<comp-create-impl,Create implicit components>>). For example, you can
+specify a single path argument to print the merged events of a CTF trace
+on the console:
+
+[role="term"]
+----
+$ babeltrace2 /path/to/trace
+----
+
+This is the equivalent of creating and connecting together:
+
+* A compcls:src.ctf.fs component with its manparam:source.ctf.fs:path
+ initialization parameter set to `/path/to/trace`.
+
+* A compcls:filter.utils.muxer component.
+
+* A compcls:sink.text.pretty component.
+
+This creates the following conversion graph:
+
+----
++------------+ +--------------------+ +------------------+
+| src.ctf.fs | | filter.utils.muxer | | sink.text.pretty |
+| [ctf-fs] | | [muxer] | | [pretty] |
+| | | | | |
+| stream0 @--->@ out @--->@ in |
+| stream1 @--->@ | +------------------+
+| stream2 @--->@ |
+| stream3 @--->@ |
++------------+ +--------------------+
+----
+
+It is equivalent to the following command:
+
+[role="term"]
+----
+$ 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
+----
+
+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:
+
+[role="term"]
+----
+$ babeltrace2 run $(babeltrace2 --run-args /path/to/trace) ...
+----
+
+The opt:--run-args-0 option is like the opt:--run-args option, but the
+printed arguments are :not: escaped and they are separated by a null
+character instead of a space. This is useful if the resulting arguments
+are not the direct input of a shell, for example if passed to
+`xargs -0`.
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+[[comp-create-expl]]
+Create explicit components
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+To explicitly create a component, use the opt:--component option. This
+option specifies:
+
+* **Optional**: The name of the component instance. You can also use the
+ opt:--name option for this.
+
+* The type of the component class to instantiate: source, filter, or
+ sink.
+
+* The name of the plugin in which to find the component class to
+ instantiate.
+
+* The name of the component class to instantiate.
+
+You can use the opt:--component option multiple times to create
+multiple components. You can instantiate the same component class
+multiple times as different component instances.
+
+Immediately following a opt:--component option on the command line, the
+created component is known as the _current component_ (until the next
+opt:--component option).
+
+The following, optional command-line options apply to the current
+component:
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'.
+
+opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, this parameter is replaced.
++
+See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:--path='PATH'::
+ Set the nlparam:path initialization parameter of the current
+ component to 'PATH' (replace the parameter if it exists).
++
+You can use this option instead of manually specifying `path="PATH"` in
+a opt:--params option to use your shell's tilde expansion (`~`). Tilde
+expansion requires the tilde to be the first character of the argument,
+which is not possible with `path="PATH"`.
+
+opt:--url='URL'::
+ Set the nlparam:url initialization parameter of the current
+ component to 'URL' (replace the parameter if it exists).
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+[[comp-create-impl]]
+Create implicit components
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+An _implicit component_ is a component which is created and added to the
+conversion graph without an explicit instantiation through the
+opt:--component option. An implicit component is easier to create than
+an explicit component: this is why the `convert` command exists, as you
+can also create and run a conversion graph with the generic
+man:babeltrace2-run(1) command.
+
+There are many ways to create implicit components with the `convert`
+command:
+
+* To create one or more implicit compcls:src.ctf.fs components (CTF
+ trace read from the file system), use one or more positional arguments
+ to specify the paths to the CTF traces to read, and do :not: specify
+ the opt:--input-format=`lttng-live` option.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace2 /path/to/trace /path/to/other/trace
+----
++
+The opt:--clock-offset and opt:--clock-offset-ns options apply to _all_
+the implicit compcls:src.ctf.fs components. For example:
++
+[role="term"]
+----
+$ babeltrace2 --clock-offset=3 trace1 trace2
+----
++
+With the command line above, two implicit compcls:src.ctf.fs components
+have their manparam:source.ctf.fs:clock-class-offset-s initialization
+parameter set to `3`, but they have different
+manparam:source.ctf.fs:path parameters (`trace1` and `trace2`).
++
+You cannot create implicit compcls:src.ctf.fs components and an implicit
+compcls:src.ctf.lttng-live component.
+
+* To create an implicit compcls:src.ctf.lttng-live component
+ (http://lttng.org/docs/#doc-lttng-live[LTTng live] input), specify the
+ opt:--input-format=`lttng-live` option and the LTTng relay daemon's
+ URL with the positional argument.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace2 --input-format=lttng-live \
+ net://localhost/host/abeille/my-session
+----
++
+You cannot create an implicit compcls:src.ctf.lttng-live component and
+implicit compcls:src.ctf.fs components.
+
+* To create an implicit compcls:filter.utils.trimmer component (trace
+ trimmer), specify the opt:--begin, opt:--end, or opt:--timerange
+ option.
++
+Examples:
++
+[role="term"]
+----
+$ babeltrace2 /path/to/trace --begin=22:14:38 --end=22:15:07
+----
++
+[role="term"]
+----
+$ babeltrace2 /path/to/trace --timerange=22:14:38,22:15:07
+----
++
+[role="term"]
+----
+$ babeltrace2 /path/to/trace --end=12:31:04.882928015
+----
+
+* To create an implicit compcls:filter.lttng-utils.debug-info (add
+ debugging information to compatible LTTng events), specify any of the
+ opt:--debug-info, opt:--debug-info-dir, opt:--debug-info-full-path, or
+ opt:--debug-info-target-prefix options.
++
+Examples:
++
+[role="term"]
+----
+$ babeltrace2 --debug-info /path/to/trace
+----
++
+[role="term"]
+----
+$ babeltrace2 /path/to/trace \
+ --debug-info-target-prefix=/tmp/tgt-root
+----
++
+[role="term"]
+----
+$ 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:
++
+--
+* Specify no other sink components, <<comp-create-expl,explicit>> or
+ implicit. The compcls:sink.text.pretty implicit component is the
+ _default_ implicit sink component. If any other explicit or implicit
+ component exists, the default compcls:sink.text.pretty sink component
+ is not automatically created.
+
+* Specify any of the opt:--clock-cycles, opt:--clock-date,
+ opt:--clock-gmt, opt:--clock-seconds, opt:--color, opt:--fields,
+ opt:--names, or opt:--no-delta options. You can also specify the
+ opt:--output option without using the opt:--output-format=`ctf` option
+ (in which case opt:--output applies to the implicit
+ compcls:sink.ctf.fs component).
+
+* Specify the opt:--output-format=`text` option.
+--
++
+Examples:
++
+[role="term"]
+----
+$ babeltrace2 /path/to/trace
+----
++
+[role="term"]
+----
+$ 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.
++
+Example:
++
+[role="term"]
+----
+$ 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.
++
+Example:
++
+[role="term"]
+----
+$ babeltrace2 /path/to/input/trace --output-format=ctf \
+ --output=my-traces
+----
+
+You can combine multiple methods to create implicit components. For
+example, you can trim an LTTng (CTF) trace, add debugging information to
+it, and write it as another CTF trace:
+
+[role="term"]
+----
+$ babeltrace2 /path/to/input/trace --timerange=22:14:38,22:15:07 \
+ --debug-info --output-format=ctf --output=out-dir
+----
+
+The equivalent man:babeltrace2-run(1) command of this `convert` command
+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
+----
+
+See <<examples,EXAMPLES>> for more examples.
+
+
+include::common-cmd-params-format.txt[]
+
+
+[[time-fmt]]
+Time option format
+~~~~~~~~~~~~~~~~~~
+The format of the arguments of the opt:--begin and opt:--end options
+is:
+
+[verse]
+$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
+
+'YYYY'::
+ 4-digit year.
+
+'MM'::
+ 2-digit month (January is `01`).
+
+'DD'::
+ 2-digit day.
+
+'hh'::
+ 2-digit hour (24-hour format).
+
+'mm'::
+ 2-digit minute.
+
+'ss'::
+ 2-digit second.
+
+'nnnnnnnnn'::
+ 9-digit nanosecond.
+
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+
+Explicit component creation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+See <<comp-create-expl,Create explicit components>> to learn how to
+use the following options.
+
+opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
+ Create a component initially named 'NAME' (if specified) from the
+ component class of type 'TYPE' named 'COMPCLS' found in the plugin
+ named 'PLUGIN', and set it as the current component.
++
+The available values for 'TYPE' are:
++
+--
+`source`::
+`src`::
+ Source component class.
+
+`filter`::
+`flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+--
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'. The names of all
+ the explicitly created components in the conversion graph must be
+ unique.
+
+opt:-p 'PARAMS', opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, replace the parameter.
+ See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:-P 'PATH', opt:--path='PATH'::
+ Set the nlparam:path initialization parameter of the current
+ component to 'PATH' (replace the parameter if it exists).
+
+opt:-u 'URL', opt:--url='URL'::
+ Set the nlparam:url initialization parameter of the current
+ component to 'URL' (replace the parameter if it exists).
+
+
+Legacy options to create implicit components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+opt:-i 'FORMAT', opt:--input-format='FORMAT'::
+ Create one or more implicit source components. The available values
+ for 'FORMAT' are:
++
+--
+`ctf`::
+ Create an implicit compcls:src.ctf.fs component for each positional
+ argument. Each positional argument sets the
+ manparam:source.ctf.fs:path initialization parameter of an
+ individual component. See <<impl-opts-ctf,Implicit
+ compcls:src.ctf.fs component>>.
++
+See man:babeltrace2-source.ctf.fs(7) to learn more about this
+component class.
+
+`lttng-live`::
+ Depending on the format of the positional argument:
++
+--
+`net[4]://RDHOST[:RDPORT]/host/TGTHOST`::
+ Print the available LTTng live sessions of the LTTng relay daemon at
+ the address `RDHOST` and port `RDPORT`, and then exit.
+
+`net[4]://RDHOST[:RDPORT]/host/TGTHOST/SESSION`::
+ Create an implicit compcls:src.ctf.lttng-live component. The
+ position argument sets the manparam:source.ctf.lttng-live:url
+ parameter of the component.
++
+Any other format for the positional argument is invalid.
++
+See man:babeltrace2-source.ctf.lttng-live(7) to learn more about
+this component class.
+--
+--
++
+You can specify at most one opt:--input-format option.
+
+opt:-o 'FORMAT', opt:--output-format='FORMAT'::
+ Create an implicit sink component. The available values for 'FORMAT'
+ are:
++
+--
+`text`::
+ Create an implicit compcls:sink.text.pretty component.
+ See <<impl-opts-text,Implicit compcls:sink.text.pretty component>>.
++
+See man: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.
++
+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.
+
+`ctf-metadata`::
+ Print the metadata text of a CTF trace and exit. The first
+ positional argument specifies the path to the CTF trace.
+--
++
+You can specify at most one opt:--output-format option.
+
+
+[[impl-opts-ctf]]
+Implicit compcls:src.ctf.fs component(s)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There is one implicit compcls:src.ctf.fs component per positional
+argument (which are trace paths), unless you specify
+opt:--input-format=`lttng-live`.
+
+See man:babeltrace2-source.ctf.fs(7) to learn more about this
+component class.
+
+opt:--clock-offset='SEC'::
+ Set the manparam:source.ctf.fs:clock-class-offset-s initialization
+ parameter of all the implicit compcls:src.ctf.fs components to
+ 'SEC'.
++
+The manparam:source.ctf.fs:clock-class-offset-s initialization parameter
+adds 'SEC' seconds to the offsets of all the clock classes that the
+component creates.
++
+You can combine this option with opt:--clock-offset-ns.
+
+opt:--clock-offset-ns='NS'::
+ Set the manparam:source.ctf.fs:clock-class-offset-ns initialization
+ parameter of all the implicit compcls:src.ctf.fs components to
+ 'NS'.
++
+The manparam:source.ctf.fs:clock-class-offset-ns initialization
+parameter adds 'NS' nanoseconds to the offsets of all the clock classes
+that the component creates.
++
+You can combine this option with opt:--clock-offset-s.
+
+
+Implicit compcls:filter.utils.trimmer component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you specify at least one of the following options, you create an
+implicit compcls:filter.utils.trimmer component.
+
+See man:babeltrace2-filter.utils.trimmer(7) to learn more about
+this component class.
+
+See <<time-fmt,Time option format>> for the format of 'BEGIN' and 'END'.
+
+opt:--begin='BEGIN'::
+ Set the manparam:filter.utils.trimmer:begin initialization parameter
+ of the component to 'BEGIN'. You cannot use this option with the
+ opt:--timerange option.
+
+opt:--end='END'::
+ Set the manparam:filter.utils.trimmer:end initialization parameter
+ of the component to 'END'. You cannot use this option with the
+ opt:--timerange option.
+
+opt:--timerange='BEGIN','END'::
+ Equivalent to opt:--begin='BEGIN' opt:--end='END'.
++
+You can also surround the whole argument with `[` and `]`.
+
+
+Implicit compcls:filter.lttng-utils.debug-info component
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you specify at least one of the following options, you create an
+implicit compcls:filter.lttng-utils.debug-info component. This component
+only alters compatible LTTng events.
+
+See man: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.
+
+opt:--debug-info-dir='DIR'::
+ Set the manparam:filter.lttng-utils.debug-info:debug-info-dir
+ initialization parameter of the component to 'DIR'.
++
+The manparam:filter.lttng-utils.debug-info:debug-info-dir parameter
+indicates where the component should find the debugging information it
+needs if it's not found in the actual executable files.
+
+opt:--debug-info-full-path::
+ Set the manparam:filter.lttng-utils.debug-info:full-path
+ initialization parameter of the component to true.
++
+When the manparam:filter.lttng-utils.debug-info:full-path parameter is
+true, the component writes the full (absolute) paths to files in its
+debugging information fields instead of just the short names.
+
+opt:--debug-info-target-prefix='PREFIX'::
+ Set the manparam:filter.lttng-utils.debug-info:target-prefix
+ initialization parameter of the component to 'PREFIX'.
++
+The manparam:filter.lttng-utils.debug-info:target-prefix parameter is a
+path to prepend to the paths to executables recorded in the trace. For
+example, if a trace contains the executable path `/usr/bin/ls` in its
+state dump events, and you specify
+opt:--debug-info-target-prefix=`/home/user/boards/xyz/root`, then the
+component opens the `/home/user/boards/xyz/root/usr/bin/ls` file to find
+debugging information.
+
+
+[[impl-opts-text]]
+=== Implicit compcls:sink.text.pretty component
+
+If you specify at least one of the following options, you create an
+implicit compcls:sink.text.pretty component. The `convert` command also
+creates a default implicit compcls:sink.text.pretty component if no
+other sink component exists.
+
+See man:babeltrace2-sink.text.pretty(7) to learn more about this
+component class.
+
+opt:--clock-cycles::
+ Set the manparam:sink.text.pretty:clock-seconds initialization
+ parameter of the component to true.
++
+The manparam:sink.text.pretty:clock-cycles parameter makes the component
+print the event time in clock cycles.
+
+opt:--clock-date::
+ Set the manparam:sink.text.pretty:clock-date initialization
+ parameter of the component to true.
++
+The manparam:sink.text.pretty:clock-date parameter makes the component
+print the date and the time of events.
+
+opt:--clock-gmt::
+ Set the manparam:sink.text.pretty:clock-gmt initialization parameter
+ of the component to true.
++
+The manparam:sink.text.pretty:clock-gmt parameter makes the component
+not apply the local timezone to the printed times.
+
+opt:--clock-seconds::
+ Set the manparam:sink.text.pretty:clock-seconds initialization
+ parameter of the component to true.
++
+The manparam:sink.text.pretty:clock-seconds parameter makes the
+component print the event times in seconds since Epoch.
+
+opt:--color='WHEN'::
+ Set the manparam:sink.text.pretty:color initialization parameter of
+ the component to 'WHEN'.
++
+The available values for 'WHEN' are:
++
+--
+`auto`::
+ Automatic color support depending on the capabilities of the
+ terminal(s) to which the standard output and error streams are
+ connected.
+
+`never`::
+ Never emit terminal color codes.
+
+`always`::
+ Always emit terminal color codes.
+--
++
+The `auto` and `always` values have no effect if the
+`BABELTRACE_TERM_COLOR` environment variable is set to `NEVER`.
+
+opt:--fields='FIELD'[,'FIELD']...::
+ For each 'FIELD', set the nlparam:field-FIELD initialization
+ parameter of the component to true.
++
+For example, opt:--fields=`trace,loglevel,emf` sets the
+manparam:sink.text.pretty:field-trace,
+manparam:sink.text.pretty:field-loglevel, and
+manparam:sink.text.pretty:field-emf initialization parameters to true.
++
+The available value for 'FIELD' are:
++
+* `trace`
+* `trace:hostname`
+* `trace:domain`
+* `trace:procname`
+* `trace:vpid`
+* `loglevel`
+* `emf`
+* `callsite`
+
+opt:--names='NAME'[,'NAME']...::
+ For each 'NAME', set the nlparam:name-NAME initialization parameter
+ of the component to true.
++
+For example, opt:--names=`payload,scope` sets the
+manparam:sink.text.pretty:name-payload and
+manparam:sink.text.pretty:name-scope initialization parameters to true.
++
+The available value for 'NAME' are:
++
+* `payload`
+* `context`
+* `scope`
+* `header`
+
+opt:--no-delta::
+ Set the manparam:sink.text.pretty:no-delta initialization parameter
+ of the component to true.
++
+When the manparam:sink.text.pretty:no-delta parameter is true, the
+component does not print the duration since the last event on the line.
+
+
+Shared options
+~~~~~~~~~~~~~~
+opt:-w 'PATH', opt:--output='PATH'::
+ 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.
++
+When you specify opt:--output-format=`ctf`, set the
+manparam:sink.ctf.fs:path initialization parameter of the implicit
+compcls:sink.ctf.fs component to 'PATH'. Otherwise, create an implicit
+compcls:sink.text.pretty component and set its
+manparam:sink.text.pretty:path initialization parameter to 'PATH'.
++
+See man:babeltrace2-sink.ctf.fs(7) and
+man:babeltrace2-sink.text.pretty(7) to learn more about those
+component classes.
+
+
+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.
++
+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.
++
+You cannot use this option with the opt:--run-args or
+opt:--stream-intersection option.
+
+
+Conversion graph configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+opt:--retry-duration='DURUS'::
+ Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+ component reports "try again later" (busy network or file system,
+ for example).
++
+Default: 100000 (100{nbsp}ms).
+
+opt:--stream-intersection::
+ Enable the stream intersection mode. In this mode, for each trace,
+ the `convert` command filters out the events and other notifications
+ which are not in the time range where _all_ the trace's streams are
+ active.
++
+All the source components, <<comp-create-expl,explicit>> and
+<<comp-create-impl,implicit>>, must have classes which support the
+`trace-info` query object to use this option. The only Babeltrace
+project's component class which supports this query object is
+compcls:source.ctf.fs.
++
+Because it is not possible to replicate with a single
+man: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.
+
+
+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.
+
+
+Command information
+~~~~~~~~~~~~~~~~~~~
+opt:-h, opt:--help::
+ Show command help and quit.
+
+
+[[examples]]
+EXAMPLES
+--------
+.Pretty-print the events of one or more CTF traces.
+====
+[role="term"]
+----
+$ babeltrace2 my-trace
+----
+
+[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-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2(1),
+man:babeltrace2-run(1),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-filter.lttng-utils.debug-info(7)
+===========================================
+:manpagetype: component class
+:revdate: 5 October 2017
+:comp: compcls:filter.lttng-utils.debug-info
+:defdebuginfoname: `debug_info`
+
+
+NAME
+----
+babeltrace2-filter.lttng-utils.debug-info - Babeltrace'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.
++
+Example: `my-program@0x401040`.
+
+[[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.
++
+Example: `load_user_config+0x194`.
+
+[[field-src]]`src` (string field)::
+ Source file path or name followed by `: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.
+
+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.
+
+
+Compile an executable for debugging information analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+With GCC or Clang, you should 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
+function.
+
+NOTE: This component class only supports the debugging information in
+DWARF format, version{nbsp}2 or later. Use the nlopt:-gdwarf or
+nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler
+options to explicitly generate DWARF debugging information.
+
+If you don't compile the executable's source files with the nlopt:-g
+option or with an equivalent option, no DWARF information is available:
+the component uses ELF symbols from the executable file instead. In this
+case, the events that the component creates do not contain the source
+file and line number (<<field-src,`src` field>>), but only the name of
+the nearest function symbol with an offset in bytes to the location in
+the executable from which the LTTng event occured (<<field-func,`func`
+field>>).
+
+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.
+
+
+LTTng prerequisites
+~~~~~~~~~~~~~~~~~~~
+A {comp} component can only analyze user space events generated by
+http://lttng.org[LTTng]{nbsp}2.8.0 or later.
+
+To get debugging information for LTTng-UST events which occur in
+executables and libraries which the system's loader loads (what
+you can see with man:ldd(1)):
+
+. Add the `ip` and `vpid` context fields to user space event records:
++
+--
+[role="term"]
+----
+$ lttng add-context --userspace --type=ip --type=vpid
+----
+--
++
+See man:lttng-add-context(1) for more details.
+
+. Enable the LTTng-UST state dump events:
++
+--
+[role="term"]
+----
+$ lttng enable-event --userspace 'lttng_ust_statedump:*'
+----
+--
++
+See man:lttng-enable-event(1) and man:lttng-ust(3) for more details.
+
+To get debugging information for LTTng-UST events which occur in
+dynamically loaded objects, for example plugins:
+
+. Do the previous steps (add context fields and enable
+ the LTTng-UST state dump events).
+
+. Enable the LTTng-UST dynamic linker tracing helper events:
++
+--
+[role="term"]
+----
+$ lttng enable-event --userspace 'lttng_ust_dl:*'
+----
+--
++
+See man:lttng-ust-dl(3) for more details.
+
+. When you are ready to trace, start your application with the
+ `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`:
++
+--
+[role="term"]
+----
+$ 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.
+
+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.
+
+The debugging information lookup order is the same as GDB's, namely:
+
+. Within the executable file itself.
+
+. Through the build ID method in the `/usr/lib/debug/.build-id`
+ directory.
+
+. In the various possible debug link locations.
+
+The component uses the first debugging information file that it finds.
+
+You can use the param:deubg-info-dir initialization parameter to
+override the default `/usr/lib/debug` directory used in the build ID and
+debug link methods.
+
+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.
+
+If the trace was recorded on a separate machine, however, you can use
+the param:target-prefix parameter to specify a prefix directory, that
+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`.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:debug-info-dir='DIR' (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:full-path=`yes` (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)::
+ 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.
+
+
+Output
+~~~~~~
+`out`::
+ Single output port to which the component sends the augmented
+ or unaltered notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+`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).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-lttng-utils(7),
+man:lttng(1),
+man:lttng-add-context(1),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-filter.utils.muxer(7)
+================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-filter.utils.muxer - Babeltrace's notification multiplexer
+filter component class
+
+
+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 component does not alter the notifications
+it receives: it only sorts them.
+
+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.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:assume-absolute-clock-classes=`yes` (boolean)::
+ Assume that all clock classes are absolute.
+
+
+PORTS
+-----
+Input
+~~~~~
+`inN`, where `N` is a decimal integer starting at 0::
+ Input port from which the component receives notifications to
+ multiplex.
++
+When you create the component, 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.
++
+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.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+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).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-utils(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-filter.utils.trimmer(7)
+==================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+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.
+
+
+[[time-param-fmt]]
+Time parameter format
+~~~~~~~~~~~~~~~~~~~~~
+The format of the param:begin and param:end parameters is:
+
+[verse]
+$$[$$__YYYY__-__MM__-__DD__ [__hh__:__mm__:]]__ss__[.__nnnnnnnnn__]
+
+'YYYY'::
+ 4-digit year.
+
+'MM'::
+ 2-digit month (January is `01`).
+
+'DD'::
+ 2-digit day.
+
+'hh'::
+ 2-digit hour (24-hour format).
+
+'mm'::
+ 2-digit minute.
+
+'ss'::
+ 2-digit second.
+
+'nnnnnnnnn'::
+ 9-digit nanosecond.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+You must specify at least one of the param:begin and param:end
+parameters.
+
+param:begin='BEGIN' (string or integer)::
+ Set the trimmer's beginning time to 'BEGIN'.
++
+If 'BEGIN' is a string, see <<time-param-fmt,Time parameter format>> for
+its format. If 'BEGIN' is an integer, it is the number of nanoseconds
+since Epoch.
++
+If 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.
+
+param:end='END' (string or integer)::
+ Set the trimmer's end time to 'END'.
++
+If 'END' is a string, see <<time-param-fmt,Time parameter format>> for
+its format. If 'END' is an integer, it is the number of nanoseconds
+since Epoch.
++
+If you don't specify this parameter, the component discards no events
+from the beginning of the trimming range.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications.
+
+
+Output
+~~~~~~
+`out`::
+ Single output port to which the components sends the notifications
+ of which the time is in the trimming range.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+`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).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-utils(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-help(1)
+==================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-help - Get help for a Babeltrace plugin or 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')
+
+
+DESCRIPTION
+-----------
+The `help` command prints the details and help text of either the plugin
+'PLUGIN' or the specific component class 'TYPE.PLUGIN.COMPCLS'.
+
+See man:babeltrace2-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+The available values for 'TYPE' are:
+
+`source` or `src`::
+ Source component class.
+
+`filter` or `flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+include::common-plugin-path-options.txt[]
+
+include::common-cmd-info-options.txt[]
+
+
+[[examples]]
+EXAMPLES
+--------
+.Get help for a plugin and all its component classes.
+====
+[role="term"]
+----
+$ babeltrace2 help my-plugin
+----
+====
+
+.Get help for a specific plugin's source component class.
+====
+[role="term"]
+----
+$ babeltrace2 help src.my-plugin.my-source
+----
+====
+
+.Get help for a specific plugin's sink component class.
+====
+[role="term"]
+----
+$ babeltrace2 help sink.my-plugin.my-sink
+----
+====
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2(1),
+man:babeltrace2-list-plugins(1)
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-intro(7)
+===================
+:manpagetype: man page
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-intro - Introduction to Babeltrace
+
+
+DESCRIPTION
+-----------
+This man page is an introduction to the Babeltrace project.
+
+The <<what-is,WHAT IS BABELTRACE?>> section lists the parts of the
+project and shows the major changes from Babeltrace{nbsp}1 to
+Babeltrace{nbsp}2 while the <<concepts,BABELTRACE CONCEPTS>> section
+defines the core concepts of Babeltrace.
+
+The <<graph-repr,TRACE PROCESSING GRAPH REPRESENTATION>> section shows
+how some <<concepts,concepts>> are visually represented in other
+Babeltrace man pages.
+
+
+[[what-is]]
+WHAT IS BABELTRACE?
+-------------------
+Babeltrace 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:
+
+[[libbabeltrace2]]Babeltrace library (libbabeltrace2)::
+ A shared library with a C API.
++
+With libbabeltrace2, you can programmatically create <<plugin,plugins>>
+and <<comp-cls,component classes>>, build and run <<graph,processing
+graphs>>, and more (see the <<concepts,BABELTRACE CONCEPTS>> section for
+more details about those concepts). All the other Babeltrace parts rely
+on this library.
+
+[[babeltrace2-1]]`babeltrace2` command::
+ A command-line interface which uses libbabeltrace2 to load plugins,
+ create a trace processing graph, create components, and run the
+ graph.
++
+You can also use `babeltrace2` to list the available plugins or to query
+an object from a component class.
++
+See man:babeltrace2(1).
+
+[[python-bindings]]Babeltrace Python bindings::
+ A Python{nbsp}3 package which offers a Pythonic interface of
+ 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.
+
+Babeltrace project's plugins::
+ The Babeltrace <<plugin,plugins>> shipped with the project.
++
+Those plugins are not special, in that they only rely on libbabeltrace2
+and you don't need them to use libbabeltrace2, man:babeltrace2(1), or the
+Python bindings.
++
+The Babeltrace project's plugins are:
++
+--
+`ctf`::
+ Common Trace Format input/output, including the LTTng live source.
++
+See man:babeltrace2-plugin-ctf(7).
+
+`lttng-utils`::
+ Graph utilities specific to http://lttng.org/[LTTng] traces.
++
+See man:babeltrace2-plugin-lttng-utils(7).
+
+`text`::
+ Text input/output.
++
+See man:babeltrace2-plugin-text(7).
+
+`utils`::
+ 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{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.
+
+Babeltrace{nbsp}1 exists since 2010. The major improvements brought by
+Babeltrace{nbsp}2 are:
+
+* Full plugin support: any user can distribute a Babeltrace plugin and,
+ as long as <<libbabeltrace2,libbabeltrace2>> finds it, any application
+ linked to libbabeltrace2 can load it and use it.
++
+Plugins are not just input and output formats: they provide source,
+filter, and sink <<comp-cls,component classes>> so that you can connect
+specialized, reusable components together in a graph to create a
+customized trace conversion or analysis device.
+
+* 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.
+
+* All the parts of the Babeltrace 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
+<<libbabeltrace2,libbabeltrace2>> and its <<python-bindings,Python
+bindings>>, but also as command-line actions and options in the
+<<babeltrace2-1,`babeltrace2` command>>. The other Babeltrace man pages
+assume that you are familiar with the following definitions.
+
+Some Babeltrace concepts are interdependent: it is normal to jump from
+one definition to another to understand the big picture.
+
+[[comp-cls]]Component class::
+ A reusable class from which you can instantiate one or more
+ <<comp,component>> instances.
++
+There are three types of component classes used to instantiate the three
+types of components (source, filter, and sink).
++
+A component class provides 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.
+
+[[comp]]Component::
+ A node within a <<graph,trace processing graph>>.
++
+There are three types of components:
++
+--
+Source component::
+ An input component which produces <<notif,notifications>>.
++
+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.
++
+Examples: filter which removes notifications based on an expression,
+filter which adds debugging information to selected events, notification
+multiplexer, trace trimmer.
+
+Sink component::
+ An output component which consumes notifications and usually writes
+ them to one or more formatted files.
++
+Examples: log file output, CTF files output, text output on the
+console.
+--
++
+Components are connected together within a <<graph,trace processing
+graph>> through their <<port,ports>>. Source components have output
+ports, sink components have input ports, and filter components have
+both.
++
+A component is the instance of a <<comp-cls,component class>>. The terms
+_component_ and _component 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.
+
+[[port]]Port::
+ A connection point, on a <<comp,component>>, from which are sent or
+ to which are received <<notif,notifications>> when the <<graph,trace
+ processing graph>> is running.
++
+An output port is where notifications are sent. An input port is where
+notifications 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.
++
+A filter or sink component receiving notifications from its input ports
+is said to _consume_ notifications.
++
+The link between an output port and input port is a <<conn,connection>>.
++
+A component can dynamically add and remove ports while a graph is
+running. For example, a compcls:filter.utils.muxer component always
+makes sure that it has at least one available input port.
+
+[[conn]]Connection::
+ The link between an output <<port,port>> and an input port through
+ which <<notif,notifications>> flow when a <<graph,trace processing
+ graph>> is running.
+
+[[notif]]Notification::
+ An atomic element sent from an output <<port,port>> to an
+ input port.
++
+A source <<comp,component>> produces notifications, while a sink
+component consumes them. A filter component can both consume and
+produce notifications.
++
+The main types of notifications are:
++
+--
+Event::
+ A trace event record within a packet.
+
+Packet beginning::
+ The beginning of a packet within a stream.
++
+A packet is a container of events.
+
+Packet end::
+ The end of a packet within a stream.
+
+Stream beginning::
+ The beginning of a stream.
++
+A stream is a container of packets.
++
+Usually, a given source component's output port sends packet and
+event notifications which belong to a single stream.
+
+Stream end::
+ The end of a stream.
+
+Discarded events::
+ A count of discarded events within a given time interval for a given
+ stream.
+
+Discarded packets::
+ A count of discarded packets within a given time interval for a
+ given stream.
+--
+
+[[graph]]Trace processing graph::
+ A https://en.wikipedia.org/wiki/Filter_graph[filter graph] where
+ nodes are <<comp,components>> and <<notif,notifications>> flow from
+ output <<port,ports>> to input ports.
++
+You can build a trace processing graph with
+<<libbabeltrace2,libbabeltrace2>>, with the <<python-bindings,Babeltrace
+Python bindings>>, or with the man:babeltrace2-run(1) and
+man:babeltrace2-convert(1) commands.
++
+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.
+
+[[plugin]]Plugin::
+ A container of <<comp-cls,component classes>> as a shared library.
++
+Each component class within a plugin has a type (source, filter, or
+sink) and a name. The type and name pair is unique within a given
+plugin.
++
+<<libbabeltrace2,libbabeltrace2>> can load a plugin (`.so` or `.dll` file)
+at run time: the result is a plugin object in which you can find a
+specific component class and instantiate it within a <<graph,trace
+processing graph>> as a <<comp,component>>.
++
+The <<babeltrace2-1,`babeltrace2` command>> uses the
+'TYPE.PLUGIN.COMPCLS' format to identify a specific component
+class within a specific plugin. 'TYPE' is either `source`, `filter`,
+or `sink`.
++
+You can list the available Babeltrace plugins with the
+man:babeltrace2-list-plugins(1) command.
+
+[[query]]Query::
+ An operation with which you can get a named object from a
+ <<comp-cls,component class>>, possibly with the help of query
+ parameters.
++
+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.
++
+You can use the man:babeltrace2-query(1) command to query a component
+class's object.
+
+
+[[graph-repr]]
+TRACE PROCESSING GRAPH REPRESENTATION
+-------------------------------------
+In the Babeltrace man pages, a component is represented with a box. The
+box has the <<comp-cls,component class>> type, <<plugin,plugin>> name,
+and component class name at the top. Just below, between square
+brackets, is its component instance name within the <<graph,trace
+processing graph>>. Each <<port,port>> is represented with an `@` symbol
+on the edge of the component box with its name inside the box. Output
+ports are on the right edge while input ports are on the left edge.
+
+For example, here's a source component box:
+
+----
++------------+
+| src.ctf.fs |
+| [my-src] |
+| |
+| stream0 @
+| stream1 @
+| stream2 @
++------------+
+----
+
+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`.
+
+A trace processing graph is represented with multiple component boxes
+connected together. The <<conn,connections>> are arrows from output
+ports to input ports.
+
+For example, here's a simple conversion graph:
+
+----
++------------+ +-----------------+ +------------------+
+| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+| [ctf] | | [muxer] | | [text] |
+| | | | | |
+| stream0 @--->@ in0 out @--->@ in |
+| stream1 @--->@ in1 | +------------------+
+| stream2 @--->@ in2 |
++------------+ @ in3 |
+ +-----------------+
+----
+
+Note that input port `in3` of component `muxer` is not currently
+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:
+
+----
+ CTF trace
+ |
+.------'
+| +------------+ +-----------------+ +------------------+
+| | src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+'->| [ctf] | | [muxer] | | [text] |
+ | | | | | |
+ | stream0 @--->@ in0 out @--->@ in |
+ | stream1 @--->@ in1 | +--+---------------+
+ | stream2 @--->@ in2 | |
+ +------------+ @ in3 | '---> Console
+ +-----------------+
+----
+
+Here's another example of a more complex graph which splits a specific
+stream using some criteria:
+
+----
++------------+ +-----------------+ +------------------+
+| src.ctf.fs | | flt.utils.muxer | | sink.text.pretty |
+| [ctf-in] | | [muxer] | | [text] |
+| | | | | |
+| stream0 @--->@ in0 out @--->@ in |
+| stream1 @--->@ in1 | +------------------+
+| stream2 @-. @ in2 |
++------------+ | +-----------------+ +-------------+
+ | | sink.ctf.fs |
+ | | [ctf-out0] |
+ | +-------------------+ | |
+ | | flt.some.splitter | .->@ in |
+ | | [splitter] | | +-------------+
+ | | | |
+ '->@ in A @-' +-------------+
+ | B @-. | sink.ctf.fs |
+ +-------------------+ | | [ctf-out1] |
+ | | |
+ '->@ in |
+ +-------------+
+----
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2(1)
--- /dev/null
+babeltrace2-list-plugins(1)
+==========================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-list-plugins - List Babeltrace plugins and their properties
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace2 list-plugins* ['GENERAL OPTIONS'] [opt:--omit-home-plugin-path]
+ [opt:--omit-system-plugin-path]
+ [opt:--plugin-path='PATH'[:__PATH__]...]
+
+
+DESCRIPTION
+-----------
+The `list-plugins` command prints a list of available Babeltrace
+plugins along with their component classes and their properties.
+
+See man:babeltrace2-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+
+include::common-cmd-plugin-path.txt[]
+
+
+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
+--------
+man:babeltrace2(1),
+man:babeltrace2-help(1),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-log(1)
+=================
+:manpagetype: program
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-log - Convert a Linux kernel ring buffer to a CTF trace
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace2-log* [opt:--with-timestamps] 'OUTPUT-PATH'
+
+
+DESCRIPTION
+-----------
+The `babeltrace2-log` tool reads the lines of a Linux kernel ring buffer,
+as printed by the man:dmesg(1) tool, from the standard input stream and
+converts them to a http://diamon.org/ctf/[CTF] trace written to the
+'OUTPUT-PATH' directory.
+
+Usage example:
+
+[role="term"]
+----
+$ dmesg | babeltrace2-log --with-timestamps my-trace
+----
+
+The events of the generated CTF trace are named `string` and contain a
+single payload string field named `str` which contains the corresponding
+ring buffer line.
+
+By default, `babeltrace2-log` does not try to extract the timestamps of
+the kernel ring buffer lines to 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 a timestamp which
+could be extracted. You can make `babeltrace2-log` extract timestamps
+from lines with the opt:--with-timestamps option.
+
+
+OPTIONS
+-------
+opt:-t, opt:--with-timestamps::
+ Extract timestamps from the kernel ring buffer lines: set
+ the created event's payload's `str` field to the rest of the line,
+ excluding any timestamp prefix.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+See the environment variables of man:babeltrace2-source.text.dmesg(7),
+man:babeltrace2-filter.utils.muxer(7), and
+man:babeltrace2-sink.ctf.fs(7).
+
+include::common-lib-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-intro(7),
+man:babeltrace2-source.text.dmesg(7),
+man:babeltrace2-filter.utils.muxer(7),
+man:babeltrace2-sink.ctf.fs(7)
--- /dev/null
+babeltrace2-plugin-ctf(7)
+========================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-plugin-ctf - Babeltrace'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.
+
+
+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).
+
+compcls:source.ctf.fs::
+ Opens one or more CTF traces on the file system and emits the
+ notifications 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.
++
+See man:babeltrace2-source.ctf.lttng-live(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-sink.ctf.fs(7),
+man:babeltrace2-source.ctf.fs(7),
+man:babeltrace2-source.ctf.lttng-live(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-plugin-lttng-utils(7)
+================================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-plugin-lttng-utils - Babeltrace'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
+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.
+
+
+COMPONENT CLASSES
+-----------------
+compcls:filter.lttng-utils.debug-info::
+ Receives notifications from its input port and creates new,
+ equivalent notifications with additionnal debugging information.
++
+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)
--- /dev/null
+babeltrace2-plugin-text(7)
+=========================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-plugin-text - Babeltrace'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.
+
+
+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).
+
+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.
++
+See man:babeltrace2-source.text.dmesg(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-sink-text.text(7),
+man:babeltrace2-source-text.dmesg(7),
+man:babeltrace2-intro(7),
--- /dev/null
+babeltrace2-plugin-utils(7)
+==========================
+:manpagetype: plugin
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-plugin-utils - Babeltrace's 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.
+
+
+COMPONENT CLASSES
+-----------------
+compcls:filter.utils.muxer::
+ Multiplexes the notifications received on its multiple input ports
+ by time to its single output port.
++
+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.
++
+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.
++
+See man:babeltrace2-sink.utils.counter(7).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-intro(7),
+man:babeltrace2-filter.utils.muxer(7),
+man:babeltrace2-filter.utils.trimmer(7),
+man:babeltrace2-sink.utils.counter(7),
+man:babeltrace2-sink.utils.dummy(7)
--- /dev/null
+babeltrace2-query(1)
+===================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-query - Query object from a component class
+
+
+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'
+
+
+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.
+
+See man:babeltrace2-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+The available values for 'TYPE' are:
+
+`source`::
+`src`::
+ Source component class.
+
+`filter`::
+`flt`::
+ Filter component class.
+
+`sink`::
+ 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.
+
+You can use the opt:--params='PARAMS' option to pass parameters to the
+component class's query function. See <<params-fmt,Parameters format>>
+for the exact format of 'PARAMS'.
+
+The output of the `query` command looks like YAML, although it is not
+guaranteed that it is YAML-compliant.
+
+See <<examples,EXAMPLES>> for usage examples.
+
+
+include::common-cmd-params-format.txt[]
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+
+Query parameters
+~~~~~~~~~~~~~~~~
+opt:-p 'PARAMS', opt:--params='PARAMS'::
+ Set the query parameters to 'PARAMS'. See <<params-fmt,Parameters
+ format>> for the exact format of 'PARAMS'.
+
+
+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.
+====
+[role="term"]
+----
+$ babeltrace2 query src.ctf.lttng-live sessions \
+ --params='url="net://RHOST/host/TGTHOST"'
+----
+====
+
+.Query the metadata info (includes the decoded 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"'
+----
+====
+
+.Query the trace info of CTF traces located on the local file system.
+====
+[role="term"]
+----
+$ babeltrace2 query src.ctf.fs trace-info \
+ --params='path="/path/to/trace"'
+----
+====
+
+.Query some object from a sink component class without parameters.
+====
+[role="term"]
+----
+$ 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)
--- /dev/null
+babeltrace2-run(1)
+=================
+:manpagetype: command
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-run - Create a trace processing graph and run it
+
+
+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'
+
+
+DESCRIPTION
+-----------
+The `run` command creates a trace processing graph and runs it.
+
+See man:babeltrace2-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+The `run` command uses libbabeltrace2 to dynamically load plugins which
+supply component classes. With the `run` command, you specify which
+component classes to instantiate as components and how they must be
+connected.
+
+The steps to write a `babeltrace2 run` command line are:
+
+. Specify which component classes to instantiate as components and
+ how. This is the 'COMPONENTS' part of the synopsis. See
+ <<create-comps,Create components>> to learn more.
+
+. Specify how to connect component instances together with one or more
+ opt:--connect options. See <<connect-comps,Connect components>> to
+ learn more.
+
+NOTE: The man:babeltrace2-convert(1) command is a specialization of the
+`run` command for the very common case of converting one or more traces:
+it generates a `run` command line and executes it. You can use its
+manopt:babeltrace2-convert(1):--run-args or
+manopt:babeltrace2-convert(1):--run-args-0 option to make it print the
+equivalent `run` command line instead.
+
+
+[[create-comps]]
+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 type of the component class to instantiate: source, filter, or
+ sink.
+
+* The name of the plugin in which to find the component class to
+ instantiate.
+
+* The name of the component class to instantiate.
+
+You can use the opt:--component option multiple times to create
+multiple components. You can instantiate the same component class
+multiple times as different component instances.
+
+At any point in the command line, the opt:--base-params sets the current
+base initialization parameters and the opt:--reset-base-params resets
+them. When you specify a opt:--component option, its initial
+initialization parameters are a copy of the current base initialization
+parameters.
+
+Immediately following a opt:--component option on the command line, the
+created component is known as the _current component_ (until the next
+opt:--component option).
+
+The following, optional command-line options apply to the current
+component:
+
+opt:--name='NAME'::
+ Set the name of the current component to 'NAME'.
+
+opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, this parameter is replaced.
++
+See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+
+[[connect-comps]]
+Connect components
+~~~~~~~~~~~~~~~~~~
+The components which you create from component classes with the
+opt:--component option (see <<create-comps,Create components>>) can
+create input and output _ports_ depending on their type. An output port
+is where notifications, like trace events, are sent. An input port is
+where notifications are received. For a given component instance, each
+port has a unique name.
+
+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.
+
+The format of a connection rule (the argument of the opt:--connect
+option) is:
+
+[verse]
+__UP-COMP-PAT__[.__UP-PORT-PAT__]:__DOWN-COMP-PAT__[.__DOWN-PORT-PAT__]
+
+'UP-COMP-PATH'::
+ Upstream component name pattern.
+
+'UP-PORT-PAT'::
+ Upstream port name pattern.
+
+'DOWN-COMP-PATH'::
+ Downstream component name pattern.
+
+'DOWN-PORT-PAT'::
+ Downstream 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:
+ 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.
+----
+
+__UP-COMP-PAT__, __UP-PORT-PAT__, __DOWN-COMP-PAT__, and
+__DOWN-PORT-PAT__ are globbing patterns where only the wildcard
+character, `*`, is special: it matches zero or more characters. You must
+escape the `*`, `?`, `[`, `.`, `:`, and :bs: characters with :bs:.
+
+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:
+
+----
+--connect='A.out*:B.in*' --connect=A:B --connect='*:C'
+----
+
+With those connection rules:
+
+* 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`.
+
+* Any other output port of component `A` is connected 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`.
+
+The `run` command fails when it cannot find an input port to which to
+connect a created output port using the provided connection
+rules.
+
+See <<examples,EXAMPLES>> for more examples.
+
+
+include::common-cmd-params-format.txt[]
+
+include::common-cmd-plugin-path.txt[]
+
+
+OPTIONS
+-------
+include::common-gen-options.txt[]
+
+
+Component creation
+~~~~~~~~~~~~~~~~~~
+opt:-b 'PARAMS', opt:--base-params='PARAMS'::
+ Set the current base parameters to 'PARAMS'. You can reset the
+ current base parameters with the opt:--reset-base-params option.
+ See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:-c $$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS', opt:--component=$$[$$__NAME__:]'TYPE'.'PLUGIN'.'COMPCLS'::
+ Create a component initially named 'NAME' (if specified) from the
+ component class of type 'TYPE' named 'COMPCLS' found in the plugin
+ named 'PLUGIN', and set it as the current component.
++
+The available values for 'TYPE' are:
++
+--
+`source`::
+`src`::
+ Source component class.
+
+`filter`::
+`flt`::
+ Filter component class.
+
+`sink`::
+ Sink component class.
+--
++
+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:-p 'PARAMS', opt:--params='PARAMS'::
+ Add 'PARAMS' to the initialization parameters of the current
+ component. If 'PARAMS' contains a key which exists in the current
+ component's initialization parameters, replace the parameter.
+ See <<params-fmt,Parameters format>> for the format of 'PARAMS'.
+
+opt:-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'. See
+ <<connect-comps,Connect components>> for the format of 'CONN-RULE'.
+
+
+Graph configuration
+~~~~~~~~~~~~~~~~~~~
+opt:--retry-duration='DURUS'::
+ Set the duration of a single retry to 'DURUS'{nbsp}µs when a
+ component reports "try again later" (busy network or file system,
+ for example).
++
+Default: 100000 (100{nbsp}ms).
+
+
+include::common-plugin-path-options.txt[]
+
+include::common-cmd-info-options.txt[]
+
+
+[[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
+----
+
+Possible resulting graph:
+
+----
++-----------------+ +-------------------+
+| src.plug.my-src | | sink.plug.my-sink |
+| [A] | | [B] |
+| | | |
+| out @--->@ in |
++-----------------+ +-------------------+
+----
+====
+
+.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
+`the-source`.
+
+[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
+----
+====
+
+.Use the opt:--base-params and opt:--reset-base-params options to set and reset the current base initialization parameters.
+====
+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`
+
+[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
+----
+====
+
+.Specify a component connection fallback rule.
+====
+In this example, any `A` output port of which the name starts with
+`foo` is connected to a `B` input port of which the name starts with
+`nin`. Any other `A` output port is connected to a `B` input port of
+which the name starts with `oth`.
+
+The order of the opt:--connect options is important here: the opposite
+order would create a system in which the first rule is always satisfied,
+and _any_ `A` output port, whatever its name, would be connected to a
+`B` input port with a name that starts with `oth`.
+
+[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*'
+----
+
+Possible resulting graph:
+
+----
++-----------------+ +-------------------+
+| src.plug.my-src | | sink.plug.my-sink |
+| [A] | | [B] |
+| | | |
+| foot @--->@ nine |
+| foodies @--->@ ninja |
+| some-port @--->@ othello |
+| hello @--->@ other |
++-----------------+ +-------------------+
+----
+====
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2(1),
+man:babeltrace2-convert(1),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-sink.ctf.fs(7)
+=========================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-sink.ctf.fs - Babeltrace'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
+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.
+
+This component guarantees that the output traces are semantically
+equivalent to the input traces. This means that a given output CTF trace
+contains:
+
+* 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.
+
+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.
+
+
+Output path
+~~~~~~~~~~~
+The path of a CTF trace is the directory which directly contains the
+metadata and data stream files as children.
+
+The rules to determine the path of a generated CTF trace are:
+
+* If the param:single-trace parameter is true, use the value of the
+ param:path parameter.
++
+Otherwise:
++
+--
+* 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.
++
+Otherwise, use `OUTPUTPATH/trace[SUFFIX]`, where `OUTPUTPATH` and
+`SUFFIX` are defined above.
+--
+
+
+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.
+
+param:single-trace=`yes` (boolean, optional)::
+ Assume that the component only receives notifications related to
+ a single source trace.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-ctf-plugin-env.txt[]
+
+
+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).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-ctf(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-sink.text.pretty(7)
+==============================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-sink.text.pretty - Babeltrace'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.
+
+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 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 for human
+consumption. You can use the param:color parameter to force the color
+support or to disable it.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:clock-cycles=`yes` (boolean)::
+ Print event times in clock cycles instead of hours, minutes,
+ seconds, and nanoseconds.
+
+param:clock-date=`yes` (boolean)::
+ Print event times _and_ dates.
+
+param:clock-gmt=`yes` (boolean)::
+ Print event times in the GMT time zone instead of the local time
+ zone.
+
+param:clock-seconds=`yes` (boolean)::
+ Print event times in seconds instead of hours, minutes,
+ seconds, and nanoseconds.
+
+param:color=(`never` | `auto` | `always`) (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:field-default=(`show` | `hide`) (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)::
+ Show or hide the event's Eclipse Modeling Framework URI field.
+
+param:field-loglevel=(`yes` | `no`) (boolean)::
+ Show or hide the event's logging level field.
+
+param:field-trace=(`yes` | `no`) (boolean)::
+ Show or hide the trace name field.
+
+param:field-trace:domain=(`yes` | `no`) (boolean)::
+ Show or hide the tracing domain field.
+
+param:field-trace:hostname=(`yes` | `no`) (boolean)::
+ Show or hide the hostname field.
+
+param:field-trace:procname=(`yes` | `no`) (boolean)::
+ Show or hide the process name field.
+
+param:field-trace:vpid=(`yes` | `no`) (boolean)::
+ Show or hide the virtual process ID field.
+
+param:name-context=(`yes` | `no`) (boolean)::
+ Show or hide the field names in the context scopes.
+
+param:name-default=(`show` | `hide`) (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)::
+ Show or hide the field names in the header scopes.
+
+param:name-payload=(`yes` | `no`) (boolean)::
+ Show or hide the field names in the event payload scopes.
+
+param:name-scope=(`yes` | `no`) (boolean)::
+ Show or hide the scope names.
+
+param:no-delta=`yes` (boolean)::
+ Do not print the time delta between consecutive lines.
+
+param:path='PATH' (string)::
+ Print the text output to the file 'PATH' instead of the standard
+ output.
+
+param:verbose=`yes` (boolean)::
+ Turn the verbose mode on.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ event notifications to pretty-print.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-text(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-sink.utils.counter(7)
+================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-sink.utils.counter - Babeltrace's notification 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.
+
+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)
+----
+
+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.
+
+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.
+
+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.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:hide-zero=`yes` (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.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications to count.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-utils(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-sink.utils.dummy(7)
+==============================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-sink.utils.dummy - Babeltrace'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.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+This component class has no initialization parameters.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications to discard.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-utils(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-source.ctf.fs(7)
+===========================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-source.ctf.fs - Babeltrace'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.
+
+
+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.
+
+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.
+
+The component skips the following files when looking for data stream
+files:
+
+* Any file which starts with `.`, including subdirectories.
+* Any non-regular file.
+
+
+[[trace-naming]]
+Trace naming
+~~~~~~~~~~~~
+A compcls:source.ctf.fs component names each trace `[HOSTNAME/]PATH`,
+with:
+
+`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.
+
+`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 `.`.
+
+For example, assume the following hierarchy:
+
+----
+/
+ home/
+ user/
+ my-traces/
+ trace1/
+ metadata
+ ...
+ node-traces/
+ server/
+ metadata
+ ...
+ client/
+ metadata
+ ...
+----
+
+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`
+
+
+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.
+
+In particular:
+
+* 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`.
+
+* 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.
+
+* 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).
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional unless indicated otherwise.
+
+param:clock-class-offset-ns (integer)::
+ Value to add, in 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.
++
+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.
+
+
+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.
+
+
+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.
+
+Parameters:
+
+`path` (string, mandatory)::
+ Path to the CTF trace directory which contains the `metadata` file.
+
+Returned object (map):
+
+`text` (string)::
+ Plain text metadata.
+
+`is-packetized` (boolean)::
+ True if the metadata stream is packetized.
+
+
+`trace-info`
+~~~~~~~~~~~~
+You can query the `trace-info` object for a set of CTF traces to get
+information about the data streams they contain, their intersection time
+range, and more.
+
+This query object requires that the processed CTF traces have the
+`timestamp_begin` and `timestamp_end` fields in their packet context
+field types.
+
+Parameters:
+
+`path` (string, mandatory)::
+ Path to a directory to recurse to find CTF traces.
+
+Returned object (array of maps, one element for each found trace):
+
+`name` (string)::
+ Trace name, as per the explanations in the <<trace-naming,Trace
+ naming>> section.
+
+`path` (string)::
+ Trace path.
+
+`range-ns` (map)::
+ Full time range of the trace.
++
+--
+`begin` (integer)::
+ Beginning time (ns since Epoch) of the trace.
+
+`end` (integer)::
+ End time (ns since Epoch) of the trace.
+--
+
+`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.
+
+`end` (integer)::
+ End time (ns since Epoch) of the trace's data stream intersection.
+--
+
+`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.
+
+`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.
+
+`end` (integer)::
+ End time (ns since Epoch) of the data stream.
+--
+--
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-ctf-plugin-env.txt[]
+
+
+Component class
+~~~~~~~~~~~~~~~
+include::common-common-compat-env.txt[]
+
+`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).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-ctf(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2-source.ctf.lttng-live(7)
+===================================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-source.ctf.lttng-live - Babeltrace'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].
+
+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.
+
+The component connects to an LTTng relay daemon using the param:url
+parameter.
+
+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.
+
+The component names each trace `[HOSTNAME/]SESSION/PATH`, with:
+
+`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.
+
+`SESSION`::
+ Tracing session name.
+
+`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
+----
+
+For example:
+
+----
+myhost/auto-20150909-223909/ust/uid/1000/64-bit
+----
+
+A compcls:source.ctf.lttng-live never blocks: it asks the downstream
+component to try again later instead.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+param:url='URL' (string, mandatory)::
+ The URL to use to connect to the LTTng relay daemon. The format
+ of 'URL' is:
++
+--
+[verse]
+net[4]://__RDHOST__[:__RDPORT__]/host/__TGTHOST__/__SESSION__
+
+'RDHOST'::
+ 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.
+
+'TGTHOST'::
+ Target's host name or IP address.
+
+'SESSION'::
+ Name of the LTTng tracing session from which to receive data.
+--
+
+
+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.
+
+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.
+
+
+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.
+
+Parameters:
+
+`url` (string, mandatory)::
+ The URL to use to connect to the LTTng relay daemon. The format
+ of 'URL' is:
++
+--
+[verse]
+net[4]://__RDHOST__[:__RDPORT__]
+
+'RDHOST'::
+ 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.
+--
+
+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.
+
+`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)::
+ Current number of LTTng live clients connected to the relay daemon
+ to receive data from this tracing session.
+
+
+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[]
+
+
+Component class
+~~~~~~~~~~~~~~~
+include::common-common-compat-env.txt[]
+
+`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).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-ctf(7),
+man:babeltrace2-intro(7),
+man:lttng-relayd(8),
+man:lttng-create(1)
--- /dev/null
+babeltrace2-source.text.dmesg(7)
+===============================
+:manpagetype: component class
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2-source.text.dmesg - Babeltrace'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
+lines of a Linux kernel ring buffer, as printed by the man:dmesg(1)
+tool, and emits corresponding event notifications on its output port.
+
+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.
+
+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.
+
+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:
+
+----
+[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.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:no-extract-timestamp=`yes` (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)::
+ 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.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-text(7),
+man:babeltrace2-intro(7)
--- /dev/null
+babeltrace2(1)
+=============
+:manpagetype: program
+:revdate: 5 October 2017
+
+
+NAME
+----
+babeltrace2 - Convert or process one or more traces, and more
+
+
+SYNOPSIS
+--------
+[verse]
+*babeltrace2* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] ['<<commands,CMD>>'] ['CMD ARGS']
+
+
+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 man:babeltrace2-intro(7) to learn more about the Babeltrace
+project and its core concepts.
+
+Most of the `babeltrace2` commands load Babeltrace plugins to perform
+their 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 specific command's
+ nlopt:--plugin-path option.
+
+. `$HOME/.local/lib/babeltrace2/plugins`
+
+. +{system_plugin_path}+
+
+You can use the man:babeltrace2-list-plugins(1) command to dynamically
+list the available plugins and what they offer. See <<plugins,PLUGINS>>
+for a list of plugins shipped with Babeltrace.
+
+
+OPTIONS
+-------
+opt:-d, opt:--debug::
+ Turn the debugging mode on.
++
+This is equivalent to opt:--log-level=`VERBOSE`.
+
+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`.
++
+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
+ `VERBOSE` level. This level should :not: be enabled in production.
+
+`VERBOSE`::
+`V`::
+ Low-level debugging context information. This level should :not: be
+ enabled in production.
+--
+
+opt:-v, opt:--verbose::
+ Turn the verbose mode on.
++
+This is equivalent to opt:--log-level=`INFO`.
+
+opt:-h, opt:--help::
+ Show help and quit.
+
+opt:-V, opt:--version::
+ Show version and quit.
+
+
+[[commands]]
+COMMANDS
+--------
+The following commands also have their own nlopt:--help option.
+
+man:babeltrace2-convert(1)::
+ Build a trace conversion graph and run it.
++
+This is the default command: you don't need to explicitly
+specify this command name to use it.
+
+man:babeltrace2-help(1)::
+ Get help for a specific plugin or plugin's component class.
+
+man:babeltrace2-list-plugins(1)::
+ List the available Babeltrace plugins and their component classes.
+
+man:babeltrace2-query(1)::
+ Query an object from a component class.
+
+man:babeltrace2-run(1)::
+ Build a trace processing graph and run it.
+
+
+[[plugins]]
+PLUGINS
+-------
+The following plugins are provided by the Babeltrace 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)
+* man:babeltrace2-source.ctf.fs(7)
+* man:babeltrace2-source.ctf.lttng-live(7)
+
+ifeval::[{enable_debug_info} == 1]
+man:babeltrace2-plugin-lttng-utils(7)::
+ Processing graph utilities for LTTng traces.
++
+* man:babeltrace2-filter.lttng-utils.debug-info(7)
+endif::[]
+
+man:babeltrace2-plugin-text(7)::
+ Text input and output.
++
+* man:babeltrace2-sink.text.pretty(7)
+* man:babeltrace2-source.text.dmesg(7)
+
+man:babeltrace2-plugin-utils(7)::
+ Processing graph utilities.
++
+* man:babeltrace2-filter.utils.muxer(7)
+* man:babeltrace2-filter.utils.trimmer(7)
+* man:babeltrace2-sink.utils.counter(7)
+* man:babeltrace2-sink.utils.dummy(7)
+
+
+include::common-cli-env.txt[]
+
+include::common-cli-files.txt[]
+
+include::common-cmd-footer.txt[]
+
+
+SEE ALSO
+--------
+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)
CLI
~~~
`BABELTRACE_CLI_LOG_LEVEL`::
- `babeltrace` CLI's log level. The available values are the same as
- for the manopt:babeltrace(1):--log-level option.
+ `babeltrace2` CLI's log level. The available values are the same as
+ for the manopt:babeltrace2(1):--log-level option.
`BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH`::
- Set to `0` to disable the warning message which `babeltrace` prints
+ Set to `0` to disable the warning message which `babeltrace2` prints
when you convert a trace with a relative path that's also the name
- of a `babeltrace` command.
+ of a `babeltrace2` command.
FILES
-----
-`$HOME/.local/lib/babeltrace/plugins`::
+`$HOME/.local/lib/babeltrace2/plugins`::
User plugin directory.
+{system_plugin_path}+::
Example:
----
-babeltrace ... --params='many=null, fresh=yes, condition=false,
+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",
option.
. *If the opt:--omit-home-plugin-path option is absent*:
- `$HOME/.local/lib/babeltrace/plugins`
+ `$HOME/.local/lib/babeltrace2/plugins`
. *If the opt:--omit-system-plugin-path option is absent*:
+{system_plugin_path}+
-You can use the man:babeltrace-list-plugins(1) command to dynamically
+You can use the man:babeltrace2-list-plugins(1) command to dynamically
list the available plugins.
`BABELTRACE_COMMON_LOG_LEVEL`::
Common functions's log level. The available values are the same as
- for the manopt:babeltrace(1):--log-level option of man:babeltrace(1).
+ 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:babeltrace(1):--log-level option of
- man:babeltrace(1).
+ 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:
~~~~~~~~~~~~
`BABELTRACE_PLUGIN_CTF_BTR_LOG_LEVEL`::
Binary type reader's log level. The available values are the same as
- for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1).
+ 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:babeltrace(1):--log-level option of
- man:babeltrace(1).
+ 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:babeltrace(1):--log-level option of
- man:babeltrace(1).
+ as for the manopt:babeltrace2(1):--log-level option of
+ man:babeltrace2(1).
General options
~~~~~~~~~~~~~~~
-See man:babeltrace(1) for more details.
+See man:babeltrace2(1) for more details.
nlopt:-d, nlopt:--debug::
Turn the debugging mode on.
`BABELTRACE_LOGGING_GLOBAL_LEVEL`::
Babeltrace library's global log level. The available values are the
- same as for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1)
+ 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
Plugin path
~~~~~~~~~~~
opt:--omit-home-plugin-path::
- Do not search for plugins in `$HOME/.local/lib/babeltrace/plugins`.
+ 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}+.
~~~~~~~~~~~~~~~~~~~~~~
`BABELTRACE_PYTHON_PLUGIN_PROVIDER_LOG_LEVEL`::
Python plugin provider's log level. The available values are the
- same as for the manopt:babeltrace(1):--log-level option of
- man:babeltrace(1).
+ same as for the manopt:babeltrace2(1):--log-level option of
+ man:babeltrace2(1).
projects / babeltrace.git / commitdiff
