From: Michael Jeanson Date: Tue, 4 Jun 2019 21:08:46 +0000 (-0400) Subject: doc: Rename to babeltrace2 X-Git-Tag: v2.0.0-rc1~737 X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=c1f82f3b94e856988cd73ac452a0e5655726eefb doc: Rename to babeltrace2 Adjust the documentation and manpages following the rename of the executables and library. Change-Id: I42cc662a94be6ece489af85d0415440bf1c1f36e Signed-off-by: Michael Jeanson Reviewed-on: https://review.lttng.org/c/babeltrace/+/1406 Tested-by: jenkins Reviewed-by: Philippe Proulx --- diff --git a/doc/api/Doxyfile.in b/doc/api/Doxyfile.in index 7a82c1cf..9715ca6b 100644 --- a/doc/api/Doxyfile.in +++ b/doc/api/Doxyfile.in @@ -141,13 +141,13 @@ WARN_AS_ERROR = NO 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" \ diff --git a/doc/api/dox/includes-build.dox b/doc/api/dox/includes-build.dox index 78c880fc..f7b42c1a 100644 --- a/doc/api/dox/includes-build.dox +++ b/doc/api/dox/includes-build.dox @@ -4,7 +4,7 @@ @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 /usr/include. If you build Babeltrace from source without specifying an installation prefix, this is /usr/local/include. @@ -23,14 +23,14 @@ but which necessarily makes the compilation slower: 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 @@ -47,7 +47,7 @@ cc -c -fpic my-plugin.c
  • 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
    • @@ -67,7 +67,7 @@ cc -c my-app.c
  • Create the executable application: @verbatim -cc my-app.o -lbabeltrace -o my-app +cc my-app.o -lbabeltrace2 -o my-app @endverbatim
    • diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index 951705df..8cc9d4f3 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -7,33 +7,33 @@ manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2))) # 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 diff --git a/doc/man/README.adoc b/doc/man/README.adoc index 1fc3bb07..1ebb48b0 100644 --- a/doc/man/README.adoc +++ b/doc/man/README.adoc @@ -15,17 +15,17 @@ the appropriate DocBook XSL stylesheet (using the `xmlto` command). 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 @@ -38,7 +38,7 @@ macro definitions used everywhere in the man page sources: +__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 @@ -51,8 +51,8 @@ Example: `opt:--verbose`, `opt:--color='WHEN'` +__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__+ diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in index a5ece768..ae414315 100644 --- a/doc/man/asciidoc-attrs.conf.in +++ b/doc/man/asciidoc-attrs.conf.in @@ -1,5 +1,5 @@ [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@" diff --git a/doc/man/babeltrace-convert.1.txt b/doc/man/babeltrace-convert.1.txt deleted file mode 100644 index aefc4c17..00000000 --- a/doc/man/babeltrace-convert.1.txt +++ /dev/null @@ -1,1005 +0,0 @@ -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 <> 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 -<>). You can also use one -of the many specific `convert` command options and arguments to create -implicit components from known component classes (see -<>). For example, you can -specify a single path argument to print the merged events of a CTF trace -on the console: - -[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 <> 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 <> 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 <> 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, <> 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 <> 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 <> 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 <> 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 <>. -+ -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 <>. -+ -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 <> 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, <> and -<>, 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) diff --git a/doc/man/babeltrace-filter.lttng-utils.debug-info.7.txt b/doc/man/babeltrace-filter.lttng-utils.debug-info.7.txt deleted file mode 100644 index e640cdef..00000000 --- a/doc/man/babeltrace-filter.lttng-utils.debug-info.7.txt +++ /dev/null @@ -1,267 +0,0 @@ -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 (<>), 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 (<>). - -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) diff --git a/doc/man/babeltrace-filter.utils.muxer.7.txt b/doc/man/babeltrace-filter.utils.muxer.7.txt deleted file mode 100644 index b35731fc..00000000 --- a/doc/man/babeltrace-filter.utils.muxer.7.txt +++ /dev/null @@ -1,86 +0,0 @@ -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) diff --git a/doc/man/babeltrace-filter.utils.trimmer.7.txt b/doc/man/babeltrace-filter.utils.trimmer.7.txt deleted file mode 100644 index 97f627d8..00000000 --- a/doc/man/babeltrace-filter.utils.trimmer.7.txt +++ /dev/null @@ -1,125 +0,0 @@ -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 <> 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 <> 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) diff --git a/doc/man/babeltrace-help.1.txt b/doc/man/babeltrace-help.1.txt deleted file mode 100644 index 13b06b3e..00000000 --- a/doc/man/babeltrace-help.1.txt +++ /dev/null @@ -1,94 +0,0 @@ -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 <> 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) diff --git a/doc/man/babeltrace-intro.7.txt b/doc/man/babeltrace-intro.7.txt deleted file mode 100644 index 101fe7a4..00000000 --- a/doc/man/babeltrace-intro.7.txt +++ /dev/null @@ -1,415 +0,0 @@ -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 <> section lists the parts of the -project and shows the major changes from Babeltrace{nbsp}1 to -Babeltrace{nbsp}2 while the <> section -defines the core concepts of Babeltrace. - -The <> section shows -how some <> 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 <> -and <>, build and run <>, and more (see the <> 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 <> 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 <> 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 <> 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 -<> and its <>, but also as command-line actions and options in the -<>. The other Babeltrace man pages -assume that you are familiar with the following definitions. - -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 - <> 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 <>. -+ -There are three types of components: -+ --- -Source component:: - An input component which produces <>. -+ -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 <> through their <>. Source components have output -ports, sink components have input ports, and filter components have -both. -+ -A component is the instance of a <>. 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 <>, from which are sent or - to which are received <> when the <> 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 <>. -+ -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 <> and an input port through - which <> flow when a <> is running. - -[[notif]]Notification:: - An atomic element sent from an output <> to an - input port. -+ -A source <> 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 <> and <> flow from - output <> to input ports. -+ -You can build a trace processing graph with -<>, with the <>, 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 <> 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. -+ -<> can load a plugin (`.so` or `.dll` file) -at run time: the result is a plugin object in which you can find a -specific component class and instantiate it within a <> as a <>. -+ -The <> 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 - <>, 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 <> type, <> name, -and component class name at the top. Just below, between square -brackets, is its component instance name within the <>. Each <> is represented with an `@` symbol -on the edge of the component box with its name inside the box. Output -ports are on the right edge while input ports are on the left edge. - -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 <> 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) diff --git a/doc/man/babeltrace-list-plugins.1.txt b/doc/man/babeltrace-list-plugins.1.txt deleted file mode 100644 index f15e9760..00000000 --- a/doc/man/babeltrace-list-plugins.1.txt +++ /dev/null @@ -1,51 +0,0 @@ -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) diff --git a/doc/man/babeltrace-log.1.txt b/doc/man/babeltrace-log.1.txt deleted file mode 100644 index 2f87ac54..00000000 --- a/doc/man/babeltrace-log.1.txt +++ /dev/null @@ -1,75 +0,0 @@ -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) diff --git a/doc/man/babeltrace-plugin-ctf.7.txt b/doc/man/babeltrace-plugin-ctf.7.txt deleted file mode 100644 index 4749104d..00000000 --- a/doc/man/babeltrace-plugin-ctf.7.txt +++ /dev/null @@ -1,49 +0,0 @@ -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) diff --git a/doc/man/babeltrace-plugin-lttng-utils.7.txt b/doc/man/babeltrace-plugin-lttng-utils.7.txt deleted file mode 100644 index fd946f8a..00000000 --- a/doc/man/babeltrace-plugin-lttng-utils.7.txt +++ /dev/null @@ -1,38 +0,0 @@ -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) diff --git a/doc/man/babeltrace-plugin-text.7.txt b/doc/man/babeltrace-plugin-text.7.txt deleted file mode 100644 index 36eee2c5..00000000 --- a/doc/man/babeltrace-plugin-text.7.txt +++ /dev/null @@ -1,44 +0,0 @@ -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), diff --git a/doc/man/babeltrace-plugin-utils.7.txt b/doc/man/babeltrace-plugin-utils.7.txt deleted file mode 100644 index e1a0a6be..00000000 --- a/doc/man/babeltrace-plugin-utils.7.txt +++ /dev/null @@ -1,60 +0,0 @@ -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) diff --git a/doc/man/babeltrace-query.1.txt b/doc/man/babeltrace-query.1.txt deleted file mode 100644 index f15e69bf..00000000 --- a/doc/man/babeltrace-query.1.txt +++ /dev/null @@ -1,128 +0,0 @@ -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 <> -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 <> 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 <> 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) diff --git a/doc/man/babeltrace-run.1.txt b/doc/man/babeltrace-run.1.txt deleted file mode 100644 index 686bd818..00000000 --- a/doc/man/babeltrace-run.1.txt +++ /dev/null @@ -1,373 +0,0 @@ -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 - <> to learn more. - -. Specify how to connect component instances together with one or more - opt:--connect options. See <> 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 <> for the format of 'PARAMS'. - - -[[connect-comps]] -Connect components -~~~~~~~~~~~~~~~~~~ -The components which you create from component classes with the -opt:--component option (see <>) can -create input and output _ports_ depending on their type. An output port -is where notifications, like trace events, are sent. An input port is -where notifications are received. For a given component instance, each -port has a unique name. - -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 <> 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 <> 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 <> 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 - <> 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) diff --git a/doc/man/babeltrace-sink.ctf.fs.7.txt b/doc/man/babeltrace-sink.ctf.fs.7.txt deleted file mode 100644 index bd04246e..00000000 --- a/doc/man/babeltrace-sink.ctf.fs.7.txt +++ /dev/null @@ -1,115 +0,0 @@ -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) diff --git a/doc/man/babeltrace-sink.text.pretty.7.txt b/doc/man/babeltrace-sink.text.pretty.7.txt deleted file mode 100644 index 8a3629d7..00000000 --- a/doc/man/babeltrace-sink.text.pretty.7.txt +++ /dev/null @@ -1,147 +0,0 @@ -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) diff --git a/doc/man/babeltrace-sink.utils.counter.7.txt b/doc/man/babeltrace-sink.utils.counter.7.txt deleted file mode 100644 index 008c9277..00000000 --- a/doc/man/babeltrace-sink.utils.counter.7.txt +++ /dev/null @@ -1,87 +0,0 @@ -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) diff --git a/doc/man/babeltrace-sink.utils.dummy.7.txt b/doc/man/babeltrace-sink.utils.dummy.7.txt deleted file mode 100644 index 9173cd34..00000000 --- a/doc/man/babeltrace-sink.utils.dummy.7.txt +++ /dev/null @@ -1,57 +0,0 @@ -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) diff --git a/doc/man/babeltrace-source.ctf.fs.7.txt b/doc/man/babeltrace-source.ctf.fs.7.txt deleted file mode 100644 index 74b08b67..00000000 --- a/doc/man/babeltrace-source.ctf.fs.7.txt +++ /dev/null @@ -1,258 +0,0 @@ -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 <> 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) diff --git a/doc/man/babeltrace-source.ctf.lttng-live.7.txt b/doc/man/babeltrace-source.ctf.lttng-live.7.txt deleted file mode 100644 index fc2803d3..00000000 --- a/doc/man/babeltrace-source.ctf.lttng-live.7.txt +++ /dev/null @@ -1,187 +0,0 @@ -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) diff --git a/doc/man/babeltrace-source.text.dmesg.7.txt b/doc/man/babeltrace-source.text.dmesg.7.txt deleted file mode 100644 index a3183388..00000000 --- a/doc/man/babeltrace-source.text.dmesg.7.txt +++ /dev/null @@ -1,80 +0,0 @@ -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) diff --git a/doc/man/babeltrace.1.txt b/doc/man/babeltrace.1.txt deleted file mode 100644 index a9cfdc89..00000000 --- a/doc/man/babeltrace.1.txt +++ /dev/null @@ -1,187 +0,0 @@ -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'] ['<>'] ['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 <> -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) diff --git a/doc/man/babeltrace2-convert.1.txt b/doc/man/babeltrace2-convert.1.txt new file mode 100644 index 00000000..1bf554f0 --- /dev/null +++ b/doc/man/babeltrace2-convert.1.txt @@ -0,0 +1,1005 @@ +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 <> 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 +<>). You can also use one +of the many specific `convert` command options and arguments to create +implicit components from known component classes (see +<>). For example, you can +specify a single path argument to print the merged events of a CTF trace +on the console: + +[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 <> 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 <> 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 <> 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, <> 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 <> 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 <> 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 <> 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 <>. ++ +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 <>. ++ +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 <> 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, <> and +<>, 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) diff --git a/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt new file mode 100644 index 00000000..ca05d708 --- /dev/null +++ b/doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt @@ -0,0 +1,267 @@ +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 (<>), 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 (<>). + +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) diff --git a/doc/man/babeltrace2-filter.utils.muxer.7.txt b/doc/man/babeltrace2-filter.utils.muxer.7.txt new file mode 100644 index 00000000..dde289a1 --- /dev/null +++ b/doc/man/babeltrace2-filter.utils.muxer.7.txt @@ -0,0 +1,86 @@ +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) diff --git a/doc/man/babeltrace2-filter.utils.trimmer.7.txt b/doc/man/babeltrace2-filter.utils.trimmer.7.txt new file mode 100644 index 00000000..cf49d9c5 --- /dev/null +++ b/doc/man/babeltrace2-filter.utils.trimmer.7.txt @@ -0,0 +1,125 @@ +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 <> 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 <> 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) diff --git a/doc/man/babeltrace2-help.1.txt b/doc/man/babeltrace2-help.1.txt new file mode 100644 index 00000000..e1b7d7c5 --- /dev/null +++ b/doc/man/babeltrace2-help.1.txt @@ -0,0 +1,94 @@ +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 <> 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) diff --git a/doc/man/babeltrace2-intro.7.txt b/doc/man/babeltrace2-intro.7.txt new file mode 100644 index 00000000..62cea708 --- /dev/null +++ b/doc/man/babeltrace2-intro.7.txt @@ -0,0 +1,415 @@ +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 <> section lists the parts of the +project and shows the major changes from Babeltrace{nbsp}1 to +Babeltrace{nbsp}2 while the <> section +defines the core concepts of Babeltrace. + +The <> section shows +how some <> 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 <> +and <>, build and run <>, and more (see the <> 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 <> 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 <> finds it, any application + linked to libbabeltrace2 can load it and use it. ++ +Plugins are not just input and output formats: they provide source, +filter, and sink <> so that you can connect +specialized, reusable components together in a graph to create a +customized trace conversion or analysis device. + +* 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 +<> and its <>, but also as command-line actions and options in the +<>. The other Babeltrace man pages +assume that you are familiar with the following definitions. + +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 + <> 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 <>. ++ +There are three types of components: ++ +-- +Source component:: + An input component which produces <>. ++ +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 <> through their <>. Source components have output +ports, sink components have input ports, and filter components have +both. ++ +A component is the instance of a <>. 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 <>, from which are sent or + to which are received <> when the <> 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 <>. ++ +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 <> and an input port through + which <> flow when a <> is running. + +[[notif]]Notification:: + An atomic element sent from an output <> to an + input port. ++ +A source <> 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 <> and <> flow from + output <> to input ports. ++ +You can build a trace processing graph with +<>, with the <>, or with the man:babeltrace2-run(1) and +man:babeltrace2-convert(1) commands. ++ +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 <> 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. ++ +<> can load a plugin (`.so` or `.dll` file) +at run time: the result is a plugin object in which you can find a +specific component class and instantiate it within a <> as a <>. ++ +The <> 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 + <>, 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 <> type, <> name, +and component class name at the top. Just below, between square +brackets, is its component instance name within the <>. Each <> is represented with an `@` symbol +on the edge of the component box with its name inside the box. Output +ports are on the right edge while input ports are on the left edge. + +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 <> 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) diff --git a/doc/man/babeltrace2-list-plugins.1.txt b/doc/man/babeltrace2-list-plugins.1.txt new file mode 100644 index 00000000..6c15e079 --- /dev/null +++ b/doc/man/babeltrace2-list-plugins.1.txt @@ -0,0 +1,51 @@ +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) diff --git a/doc/man/babeltrace2-log.1.txt b/doc/man/babeltrace2-log.1.txt new file mode 100644 index 00000000..c88056c9 --- /dev/null +++ b/doc/man/babeltrace2-log.1.txt @@ -0,0 +1,75 @@ +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) diff --git a/doc/man/babeltrace2-plugin-ctf.7.txt b/doc/man/babeltrace2-plugin-ctf.7.txt new file mode 100644 index 00000000..9cc93ed9 --- /dev/null +++ b/doc/man/babeltrace2-plugin-ctf.7.txt @@ -0,0 +1,49 @@ +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) diff --git a/doc/man/babeltrace2-plugin-lttng-utils.7.txt b/doc/man/babeltrace2-plugin-lttng-utils.7.txt new file mode 100644 index 00000000..c80b1040 --- /dev/null +++ b/doc/man/babeltrace2-plugin-lttng-utils.7.txt @@ -0,0 +1,38 @@ +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) diff --git a/doc/man/babeltrace2-plugin-text.7.txt b/doc/man/babeltrace2-plugin-text.7.txt new file mode 100644 index 00000000..f88db0b4 --- /dev/null +++ b/doc/man/babeltrace2-plugin-text.7.txt @@ -0,0 +1,44 @@ +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), diff --git a/doc/man/babeltrace2-plugin-utils.7.txt b/doc/man/babeltrace2-plugin-utils.7.txt new file mode 100644 index 00000000..49efecbf --- /dev/null +++ b/doc/man/babeltrace2-plugin-utils.7.txt @@ -0,0 +1,60 @@ +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) diff --git a/doc/man/babeltrace2-query.1.txt b/doc/man/babeltrace2-query.1.txt new file mode 100644 index 00000000..d5483b97 --- /dev/null +++ b/doc/man/babeltrace2-query.1.txt @@ -0,0 +1,128 @@ +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 <> +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 <> 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 <> 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) diff --git a/doc/man/babeltrace2-run.1.txt b/doc/man/babeltrace2-run.1.txt new file mode 100644 index 00000000..dcdd26b8 --- /dev/null +++ b/doc/man/babeltrace2-run.1.txt @@ -0,0 +1,373 @@ +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 + <> to learn more. + +. Specify how to connect component instances together with one or more + opt:--connect options. See <> to + learn more. + +NOTE: The man:babeltrace2-convert(1) command is a specialization of the +`run` command for the very common case of converting one or more traces: +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 <> for the format of 'PARAMS'. + + +[[connect-comps]] +Connect components +~~~~~~~~~~~~~~~~~~ +The components which you create from component classes with the +opt:--component option (see <>) can +create input and output _ports_ depending on their type. An output port +is where notifications, like trace events, are sent. An input port is +where notifications are received. For a given component instance, each +port has a unique name. + +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 <> 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 <> 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 <> 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 + <> 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) diff --git a/doc/man/babeltrace2-sink.ctf.fs.7.txt b/doc/man/babeltrace2-sink.ctf.fs.7.txt new file mode 100644 index 00000000..aab42675 --- /dev/null +++ b/doc/man/babeltrace2-sink.ctf.fs.7.txt @@ -0,0 +1,115 @@ +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) diff --git a/doc/man/babeltrace2-sink.text.pretty.7.txt b/doc/man/babeltrace2-sink.text.pretty.7.txt new file mode 100644 index 00000000..3fd4ae1d --- /dev/null +++ b/doc/man/babeltrace2-sink.text.pretty.7.txt @@ -0,0 +1,147 @@ +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) diff --git a/doc/man/babeltrace2-sink.utils.counter.7.txt b/doc/man/babeltrace2-sink.utils.counter.7.txt new file mode 100644 index 00000000..708cfa6f --- /dev/null +++ b/doc/man/babeltrace2-sink.utils.counter.7.txt @@ -0,0 +1,87 @@ +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) diff --git a/doc/man/babeltrace2-sink.utils.dummy.7.txt b/doc/man/babeltrace2-sink.utils.dummy.7.txt new file mode 100644 index 00000000..cb4b52db --- /dev/null +++ b/doc/man/babeltrace2-sink.utils.dummy.7.txt @@ -0,0 +1,57 @@ +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) diff --git a/doc/man/babeltrace2-source.ctf.fs.7.txt b/doc/man/babeltrace2-source.ctf.fs.7.txt new file mode 100644 index 00000000..8fafb076 --- /dev/null +++ b/doc/man/babeltrace2-source.ctf.fs.7.txt @@ -0,0 +1,258 @@ +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 <> 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) diff --git a/doc/man/babeltrace2-source.ctf.lttng-live.7.txt b/doc/man/babeltrace2-source.ctf.lttng-live.7.txt new file mode 100644 index 00000000..d3b4f47e --- /dev/null +++ b/doc/man/babeltrace2-source.ctf.lttng-live.7.txt @@ -0,0 +1,187 @@ +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) diff --git a/doc/man/babeltrace2-source.text.dmesg.7.txt b/doc/man/babeltrace2-source.text.dmesg.7.txt new file mode 100644 index 00000000..f24d4eec --- /dev/null +++ b/doc/man/babeltrace2-source.text.dmesg.7.txt @@ -0,0 +1,80 @@ +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) diff --git a/doc/man/babeltrace2.1.txt b/doc/man/babeltrace2.1.txt new file mode 100644 index 00000000..413930c9 --- /dev/null +++ b/doc/man/babeltrace2.1.txt @@ -0,0 +1,187 @@ +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'] ['<>'] ['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 <> +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) diff --git a/doc/man/common-cli-env.txt b/doc/man/common-cli-env.txt index 85140e8e..82e1b740 100644 --- a/doc/man/common-cli-env.txt +++ b/doc/man/common-cli-env.txt @@ -7,10 +7,10 @@ include::common-ppp-env.txt[] 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. diff --git a/doc/man/common-cli-files.txt b/doc/man/common-cli-files.txt index c2451a16..c9659cea 100644 --- a/doc/man/common-cli-files.txt +++ b/doc/man/common-cli-files.txt @@ -1,6 +1,6 @@ FILES ----- -`$HOME/.local/lib/babeltrace/plugins`:: +`$HOME/.local/lib/babeltrace2/plugins`:: User plugin directory. +{system_plugin_path}+:: diff --git a/doc/man/common-cmd-params-format.txt b/doc/man/common-cmd-params-format.txt index 4acce3d7..c8cefc0e 100644 --- a/doc/man/common-cmd-params-format.txt +++ b/doc/man/common-cmd-params-format.txt @@ -41,7 +41,7 @@ You may put whitespaces around the individual `=` (assignment) and `,` 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", diff --git a/doc/man/common-cmd-plugin-path.txt b/doc/man/common-cmd-plugin-path.txt index ae8afc3d..8527de9f 100644 --- a/doc/man/common-cmd-plugin-path.txt +++ b/doc/man/common-cmd-plugin-path.txt @@ -10,10 +10,10 @@ search path for Babeltrace plugins is, in this order: 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. diff --git a/doc/man/common-common-compat-env.txt b/doc/man/common-common-compat-env.txt index ee17f8f2..3c2f3ed9 100644 --- a/doc/man/common-common-compat-env.txt +++ b/doc/man/common-common-compat-env.txt @@ -1,11 +1,11 @@ `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: diff --git a/doc/man/common-ctf-plugin-env.txt b/doc/man/common-ctf-plugin-env.txt index a4ecb483..4b8affd5 100644 --- a/doc/man/common-ctf-plugin-env.txt +++ b/doc/man/common-ctf-plugin-env.txt @@ -2,15 +2,15 @@ ~~~~~~~~~~~~ `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). diff --git a/doc/man/common-gen-options.txt b/doc/man/common-gen-options.txt index 58b3b09b..413f3050 100644 --- a/doc/man/common-gen-options.txt +++ b/doc/man/common-gen-options.txt @@ -1,6 +1,6 @@ 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. diff --git a/doc/man/common-lib-env.txt b/doc/man/common-lib-env.txt index 179c98d3..dc7c9779 100644 --- a/doc/man/common-lib-env.txt +++ b/doc/man/common-lib-env.txt @@ -7,8 +7,8 @@ include::common-common-compat-env.txt[] `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 diff --git a/doc/man/common-plugin-path-options.txt b/doc/man/common-plugin-path-options.txt index 446ab003..7e114fa3 100644 --- a/doc/man/common-plugin-path-options.txt +++ b/doc/man/common-plugin-path-options.txt @@ -1,7 +1,7 @@ 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}+. diff --git a/doc/man/common-ppp-env.txt b/doc/man/common-ppp-env.txt index f2fa3539..49cc7720 100644 --- a/doc/man/common-ppp-env.txt +++ b/doc/man/common-ppp-env.txt @@ -2,5 +2,5 @@ Python plugin provider ~~~~~~~~~~~~~~~~~~~~~~ `BABELTRACE_PYTHON_PLUGIN_PROVIDER_LOG_LEVEL`:: Python plugin provider's log level. The available values are the - same as for the manopt:babeltrace(1):--log-level option of - man:babeltrace(1). + same as for the manopt:babeltrace2(1):--log-level option of + man:babeltrace2(1).