X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fman%2Fbabeltrace2.1.txt;h=beb4d67941228ada043b4766720d07c0526a27cc;hb=e70712b34fcae860414660c6b10451f57b50c25d;hp=b2d69de05c158ff722c8c9d8df8b33b636ec8019;hpb=0713ec72ea9f82718c4d54324d6f80eec9c357e0;p=babeltrace.git diff --git a/doc/man/babeltrace2.1.txt b/doc/man/babeltrace2.1.txt index b2d69de0..beb4d679 100644 --- a/doc/man/babeltrace2.1.txt +++ b/doc/man/babeltrace2.1.txt @@ -1,187 +1,226 @@ -babeltrace2(1) -============= += babeltrace2(1) :manpagetype: program -:revdate: 5 October 2017 +:revdate: 14 September 2019 -NAME ----- +== NAME + babeltrace2 - Convert or process one or more traces, and more -SYNOPSIS --------- +== SYNOPSIS + [verse] -*babeltrace2* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] ['<>'] ['CMD ARGS'] +*babeltrace2* [opt:--debug | opt:--verbose | opt:--log-level='LVL'] + [opt:--omit-home-plugin-path] [opt:--omit-system-plugin-path] + [opt:--plugin-path='PATH'[:__PATH__]...] ['<>'] ['CMD ARGS'] + + +== DESCRIPTION + +`babeltrace2` is an open-source trace converter and processor +command-line program. The tool can open one or more traces and convert +between multiple formats, possibly with one or more filters in the +conversion path, and perform other operations depending on the +command 'CMD' (see <>). +[NOTE] +-- +You might be looking for the man:babeltrace2-convert(1) command's +manual page; the `convert` command is the default command of +`babeltrace2` and is backward compatible with man:babeltrace(1). -DESCRIPTION ------------ -`babeltrace2` is an open-source trace converter and processor. The tool -can convert from one trace format to another, possibly with one or more -filters in the conversion path, and perform other operations depending -on the command 'CMD'. +See <> for `convert` command examples. +-- -See man:babeltrace2-intro(7) to learn more about the Babeltrace -project and its core concepts. +include::common-see-babeltrace2-intro.txt[] -Most of the `babeltrace2` commands load Babeltrace plugins to perform -their operation. The search path for Babeltrace plugins is, in this -order: +Most of the `babeltrace2` commands load Babeltrace~2 plugins to +perform their operation. The search path for Babeltrace~2 plugins +is, in this order: -. The colon-separated list of directories in the - `BABELTRACE_PLUGIN_PATH` environment variable. +. The colon-separated (or semicolon, on Windows) list of directories in + the `BABELTRACE_PLUGIN_PATH` environment variable. -. The colon-separated list of directories in the specific command's - nlopt:--plugin-path option. +. The colon-separated (or semicolon, on Windows) list of directories in + the opt:--plugin-path option. . `$HOME/.local/lib/babeltrace2/plugins` . +{system_plugin_path}+ You can use the man:babeltrace2-list-plugins(1) command to dynamically -list the available plugins and what they offer. See <> -for a list of plugins shipped with Babeltrace. +list the available plugins and what they offer. See +<> for a list of plugins shipped with +Babeltrace~2. -OPTIONS -------- -opt:-d, opt:--debug:: - Turn the debugging mode on. -+ -This is equivalent to opt:--log-level=`TRACE`. +== OPTIONS -opt:-l 'LVL', opt:--log-level='LVL':: - Set the log level of all known Babeltrace loggers to 'LVL'. You - can override the level of a specific logger with a dedicated - log level environment variable. If you don't specify this option, - it is equivalent to nlopt:--log-level=`WARNING`. +opt:-d:: +opt:--debug:: + Legacy option: this is equivalent to opt:--log-level=`TRACE`. + +opt:-l 'LVL':: +opt:--log-level='LVL':: + Set the log level of all known Babeltrace~2 loggers to 'LVL', + including individual components for the man:babeltrace2-convert(1) + and man:babeltrace2-run(1) commands. ++ +You can override the log level of a specific component with the +nlopt:--log-level option of the man:babeltrace2-convert(1) or +man:babeltrace2-run(1) commands. ++ +You can override the log level of the library with the +`LIBBABELTRACE2_INIT_LOG_LEVEL` environment variable. ++ +You can override the log level of the CLI with the +`BABELTRACE_CLI_LOG_LEVEL` environment variable. ++ +You can override the log level of the Babeltrace~2 Python bindings +with the `BABELTRACE_PYTHON_BT2_LOG_LEVEL` environment variable. + The available values for 'LVL' are: + -- -`NONE`:: -`N`:: - Logging is disabled. - -`FATAL`:: -`F`:: - Severe errors that lead the execution to abort immediately. This - level should be enabled in production. - -`ERROR`:: -`E`:: - Errors that might still allow the execution to continue. Usually, - once one or more errors are reported at this level, the application, - plugin, or library won't perform any more useful task, but it should - still exit cleanly. This level should be enabled in production. - -`WARN`:: -`WARNING`:: -`W`:: - Potentially harmful situations which still allow the execution - to continue. This level should be enabled in production. - -`INFO`:: -`I`:: - Informational messages that highlight progress or important states - of the application, plugin, or library. This level can be enabled in - production. - -`DEBUG`:: -`D`:: - Debugging information, with a higher level of details than the - `TRACE` level. This level should :not: be enabled in production. - -`TRACE`:: -`T`:: - Low-level debugging context information. This level should :not: be - enabled in production. +include::common-log-levels.txt[] -- -opt:-v, opt:--verbose:: - Turn the verbose mode on. +opt:--omit-home-plugin-path:: + Do not search for plugins in `$HOME/.local/lib/babeltrace2/plugins`. + +opt:--omit-system-plugin-path:: + Do not search for plugins in +{system_plugin_path}+. + +opt:--plugin-path='PATH'[:__PATH__]...:: + Add 'PATH' to the list of paths in which plugins can be found. + +opt:-v:: +opt:--verbose:: + Legacy option: this is equivalent to opt:--log-level=`INFO`. + -This is equivalent to opt:--log-level=`INFO`. +If 'CMD' is `convert` or is missing, then this also sets the +manparam:sink.text.pretty:verbose parameter of the implicit +compcls:sink.text.pretty component (see +man:babeltrace2-sink.text.pretty(7)) to true. + -opt:-h, opt:--help:: +opt:-h:: +opt:--help:: Show help and quit. -opt:-V, opt:--version:: +opt:-V:: +opt:--version:: Show version and quit. [[commands]] -COMMANDS --------- +== COMMANDS + The following commands also have their own nlopt:--help option. -man:babeltrace2-convert(1):: - Build a trace conversion graph and run it. +`convert`:: + Convert one or more traces to a given format, possibly with filters + in the conversion path. ++ +This is the default command: you don't need to explicitly specify this +command's name to use it. ++ +This command is backward compatible with the man:babeltrace(1) program. + -This is the default command: you don't need to explicitly -specify this command name to use it. +See man:babeltrace2-convert(1). -man:babeltrace2-help(1):: +`help`:: Get help for a specific plugin or plugin's component class. ++ +See man:babeltrace2-help(1). -man:babeltrace2-list-plugins(1):: - List the available Babeltrace plugins and their component classes. +`list-plugins`:: + List the available Babeltrace~2 plugins and their component + classes. ++ +See man:babeltrace2-list-plugins(1). -man:babeltrace2-query(1):: +`query`:: Query an object from a component class. ++ +See man:babeltrace2-query(1). -man:babeltrace2-run(1):: +`run`:: Build a trace processing graph and run it. ++ +See man:babeltrace2-run(1). [[plugins]] -PLUGINS -------- -The following plugins are provided by the Babeltrace project itself: +== PROJECT'S PLUGINS + +The following plugins are provided by the Babeltrace~2 project +itself. man:babeltrace2-plugin-ctf(7):: CTF trace input (from the file system and from the LTTng-live protocol) and output to the file system. + -* man:babeltrace2-sink.ctf.fs(7) +Component classes: ++ * man:babeltrace2-source.ctf.fs(7) * man:babeltrace2-source.ctf.lttng-live(7) +* man:babeltrace2-sink.ctf.fs(7) ifeval::[{enable_debug_info} == 1] man:babeltrace2-plugin-lttng-utils(7):: Processing graph utilities for LTTng traces. + +Component class: ++ * man:babeltrace2-filter.lttng-utils.debug-info(7) endif::[] man:babeltrace2-plugin-text(7):: - Text input and output. + Plain text input and output. ++ +Component classes: + -* man:babeltrace2-sink.text.pretty(7) * man:babeltrace2-source.text.dmesg(7) +* man:babeltrace2-sink.text.details(7) +* man:babeltrace2-sink.text.pretty(7) man:babeltrace2-plugin-utils(7):: Processing graph utilities. + +Component classes: ++ * man:babeltrace2-filter.utils.muxer(7) * man:babeltrace2-filter.utils.trimmer(7) * man:babeltrace2-sink.utils.counter(7) * man:babeltrace2-sink.utils.dummy(7) +[[examples]] +== EXAMPLES + +The following examples are the same as the man:babeltrace2-convert(1) +manual page's examples because `convert` is the default `babeltrace2` +program's command. + +include::common-convert-examples.txt[] + + include::common-cli-env.txt[] + include::common-cli-files.txt[] + include::common-cmd-footer.txt[] -SEE ALSO --------- +== SEE ALSO + +man:babeltrace2-intro(7), man:babeltrace2-convert(1), man:babeltrace2-help(1), man:babeltrace2-list-plugins(1), man:babeltrace2-query(1), -man:babeltrace2-run(1), -man:babeltrace2-intro(7) +man:babeltrace2-run(1)