From: Philippe Proulx Date: Tue, 28 Feb 2017 19:41:57 +0000 (-0500) Subject: Add modern Babeltrace man pages X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=0659f3af3ca96d2b622afb6603eff711d9edc0ab Add modern Babeltrace man pages The configuration to generate man pages from their AsciiDoc sources is the same as the LTTng-tools setup, although doc/man/README.adoc is specific to the Babeltrace project. See doc/man/README.adoc for more details. This patch also removes legacy documentation files of which the content is now in the new man pages. Signed-off-by: Philippe Proulx Signed-off-by: Jérémie Galarneau --- diff --git a/configure.ac b/configure.ac index 3b03bc3a..60b48d04 100644 --- a/configure.ac +++ b/configure.ac @@ -455,6 +455,14 @@ AC_ARG_ENABLE([built-in-python-plugin-support], [enable_built_in_python_plugin_support=no] ) +# Man pages +# Enabled by default +AC_ARG_ENABLE([man-pages], + [AS_HELP_STRING([--disable-man-pages], [Do not build and install man pages (already built in a distributed tarball])], + [], dnl AC_ARG_ENABLE will fill enable_built_in_plugins with the user choice + [enable_man_pages=yes] +) + # Set automake variables for optionnal feature conditionnals in Makefile.am AM_CONDITIONAL([ENABLE_PYTHON_BINDINGS], [test "x$enable_python_bindings" = xyes]) @@ -464,6 +472,7 @@ AM_CONDITIONAL([ENABLE_DEBUG_INFO], [test "x$enable_debug_info" = xyes]) AM_CONDITIONAL([ENABLE_API_DOC], [test "x$enable_api_doc" = xyes]) AM_CONDITIONAL([ENABLE_BUILT_IN_PLUGINS], [test "x$enable_built_in_plugins" = xyes]) AM_CONDITIONAL([ENABLE_BUILT_IN_PYTHON_PLUGIN_SUPPORT], [test "x$enable_built_in_python_plugin_support" = xyes]) +AM_CONDITIONAL([ENABLE_MAN_PAGES], [test "x$enable_man_pages" = xyes]) # Set defines for optionnal features conditionnals in the source code @@ -485,6 +494,13 @@ AS_IF([test "x$enable_built_in_python_plugin_support" = xyes], [AC_DEFINE([BT_BUILT_IN_PYTHON_PLUGIN_SUPPORT], [1], [Define to 1 to register plug-in attributes in static executable sections])] ) +AS_IF([test "x$enable_debug_info" = xyes], + [ENABLE_DEBUG_INFO_VAL=1], + [ENABLE_DEBUG_INFO_VAL=0] +) + +AC_SUBST([ENABLE_DEBUG_INFO_VAL]) + # Check for conflicting optional features user choices @@ -593,6 +609,55 @@ AS_IF([test "x$enable_api_doc" = "xyes"], ] ) +have_asciidoc_xmlto=no +warn_prebuilt_man_pages=no + +AS_IF([test "x$enable_man_pages" = "xyes"], [ + AC_PATH_PROG([ASCIIDOC], [asciidoc], [no]) + AC_PATH_PROG([XMLTO], [xmlto], [no]) + + AS_IF([test "x$ASCIIDOC" = "xno" || test "x$XMLTO" = "xno"], [ + AS_IF([test "x$in_git_repo" = "xyes"], [ + # this is an error because we're in the Git repo, which + # means the man pages are not already generated for us, + # thus asciixmlto are required because we were asked + # to build the man pages + AC_MSG_ERROR([ +You need asciidoc and xmlto to build the Babeltrace man pages. Use +--disable-man-pages to disable building the man pages, in which case +they will not be installed. + ]) + ], [ + # only warn here: since we're in the tarball, the man + # pages should already be generated at this point, thus + # asciidoc/xmlto are not strictly required + warn_prebuilt_man_pages=yes + ]) + ], [ + have_asciidoc_xmlto=yes + ]) +]) + +# export AsciiDoc and xmlto existence +AM_CONDITIONAL([HAVE_ASCIIDOC_XMLTO], [test "x$have_asciidoc_xmlto" = "xyes"]) + +# a wonderful hack that seems necessary because $libdir is +# literally `${exec_prefix}/lib`, and $exec_prefix is set to `NONE` +# by autoconf when it's not specified by the user +AS_IF([test "x$exec_prefix" = xNONE], [ + AS_IF([test "x$prefix" = xNONE], [ + PREFIX="$ac_default_prefix" + ], [ + PREFIX="$prefix" + ]) + + LIBDIR="$PREFIX/lib" +], [ + LIBDIR="$libdir" +]) + +AC_SUBST(LIBDIR) + # Set global CFLAGS in AM_CFLAGS AM_CFLAGS="-Wall -Wformat $PTHREAD_CFLAGS $GLIB_CFLAGS" @@ -657,6 +722,8 @@ AC_CONFIG_FILES([ doc/bindings/Makefile doc/bindings/python/Makefile doc/contributing-images/Makefile + doc/man/Makefile + doc/man/asciidoc-attrs.conf lib/Makefile lib/prio_heap/Makefile lib/plugin/Makefile @@ -790,6 +857,28 @@ PPRINT_PROP_BOOL([Built-in Python plugin support], $value) AS_ECHO PPRINT_SUBTITLE([Documentation]) + +# man pages build enabled/disabled +m4_pushdef([build_man_pages_msg], [Build and install man pages]) + +AS_IF([test "x$enable_man_pages" != "xno"], [ + AS_IF([test "x$in_git_repo" = "xyes"], [ + PPRINT_PROP_BOOL([build_man_pages_msg], 1) + ], [ + AS_IF([test "x$have_asciidoc_xmlto" = "xyes"], [ + PPRINT_PROP_BOOL([build_man_pages_msg], 1) + ], [ + PPRINT_PROP_STRING([build_man_pages_msg], + [${PPRINT_COLOR_BLDGRN}yes (already built)], + $PPRINT_COLOR_SUBTITLE) + ]) + ]) +], [ + PPRINT_PROP_BOOL([build_man_pages_msg], 0) +]) + +m4_popdef([build_man_pages_msg]) + test "x$enable_api_doc" = "xyes" && value=1 || value=0 PPRINT_PROP_BOOL([HTML API documentation], $value) test "x$enable_python_bindings_doc" = "xyes" && value=1 || value=0 diff --git a/doc/Makefile.am b/doc/Makefile.am index 67a1fb87..7d7307b2 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,9 +1,7 @@ -SUBDIRS = bindings contributing-images +SUBDIRS = bindings contributing-images man if ENABLE_API_DOC SUBDIRS += api endif -dist_man_MANS = babeltrace.1 babeltrace-log.1 - -EXTRA_DIST = API.txt lttng-live.txt +EXTRA_DIST = API.txt diff --git a/doc/babeltrace-log.1 b/doc/babeltrace-log.1 deleted file mode 100644 index 549ea8f0..00000000 --- a/doc/babeltrace-log.1 +++ /dev/null @@ -1,68 +0,0 @@ -.TH "BABELTRACE-LOG" "1" "February 16, 2012" "" "" - -.SH "NAME" -babeltrace-log \(em Babeltrace Log Converter - -.SH "SYNOPSIS" - -.PP -.nf -babeltrace-log [OPTIONS] OUTPUT -.fi -.SH "DESCRIPTION" - -.PP -Convert from a text log (read from standard input) to CTF. - -.PP -This program follows the usual GNU command line syntax with long options -starting with two dashes. Below is a summary of the available options. -.PP - -.TP -.BR "OUTPUT" -Output trace path -.TP -.BR "-t" -With timestamps (format: [sec.usec] string\\n) -.TP - -.SH "SEE ALSO" - -.PP -babeltrace(1), lttng(1), lttng-ust(3), lttng-sessiond(8) -.PP -.SH "BUGS" - -.PP -No knows bugs at this point. - -If you encounter any issues or usability problem, please report it on -our mailing list to help improve this -project. -.SH "CREDITS" - -Babeltrace and the babeltrace library are distributed under the MIT -license. See the files LICENSE and mit-license.txt for details. -.PP -A Web site is available at http://www.efficios.com/babeltrace for more -information on Babeltrace and the Common Trace Format. See -http://lttng.org for more information on the LTTng project. -.PP -Mailing list for support and development: . -.PP -You can find us on IRC server irc.oftc.net (OFTC) in #lttng. -.PP -.SH "THANKS" - -Thanks to the Linux Foundation and Ericsson for funding part of this -work. Thanks to the Multicore Association Tool Infrastructure Working -Group for their active role in the creation of the Common Trace Format. -.PP -.SH "AUTHORS" - -.PP -Babeltrace was originally written by Mathieu Desnoyers, with additional -contributions from various other people. It is currently maintained by -Mathieu Desnoyers . -.PP diff --git a/doc/babeltrace.1 b/doc/babeltrace.1 deleted file mode 100644 index 67bbd576..00000000 --- a/doc/babeltrace.1 +++ /dev/null @@ -1,143 +0,0 @@ -.TH "BABELTRACE" "1" "February 6, 2012" "" "" - -.SH "NAME" -babeltrace \(em Babeltrace Trace Viewer and Converter - -.SH "SYNOPSIS" - -.PP -.nf -babeltrace [OPTIONS] FILE... -.fi -.SH "DESCRIPTION" - -.PP -Babeltrace is a trace viewer and converter reading and writing the -Common Trace Format (CTF). Its main use is to pretty-print CTF traces -into a human-readable text output ordered by time. - -.PP -This program follow the usual GNU command line syntax with long options -starting with two dashes. Below is a summary of the available options. -.PP - -.TP -.BR "FILE" -Input trace FILE(s) or directory(ies) -.TP -.BR "-w, --output OUTPUT" -Output trace path (default: stdout) -.TP -.BR "-i, --input-format FORMAT" -Input trace format (default: ctf) -.TP -.BR "-o, --output-format FORMAT" -Output trace format (default: text) -.TP -.BR "-h, --help" -This help message -.TP -.BR "-l, --list" -List available formats -.TP -.BR "-v, --verbose" -Verbose mode (or set BABELTRACE_VERBOSE environment variable) -.TP -.BR "-d, --debug" -Debug mode (or set BABELTRACE_DEBUG environment variable) -.TP -.BR "--no-delta" -Do not print time delta between consecutive events -.TP -.BR "-n, --names name1<,name2,...>" -Print field names: (payload OR args OR arg), none, all, scope, header, -(context OR ctx), (default: payload,context). -.TP -.BR "-f, --fields name1<,name2,...>" -Print additional fields: all, trace, trace:hostname, trace:domain, -trace:procname, trace:vpid, loglevel. -.TP -.BR "--clock-cycles" -Disregard internal clock offset (use raw value) -.TP -.BR "--clock-offset seconds" -Clock offset in seconds -.TP -.BR "--clock-seconds" -Print the timestamps as [sec.ns] (default is: [hh:mm:ss.ns]) -.TP -.BR "--clock-date" -Print clock date -.TP -.BR "--clock-gmt" -Print clock in GMT time zone (default: local time zone) -.TP -.BR "--stream-intersection" -Only print events when all streams are active -.TP -.BR "--debug-info-dir" -Directory in which to look for debugging information files (default: /usr/lib/debug/) -.TP -.BR "--debug-info-target-prefix" -Directory to use as a prefix for executable lookup -.TP -.BR "--debug-info-full-path" -Show full debug info source and binary paths (if available) -.TP - -.fi -Formats available: ctf, lttng-live, dummy, text, ctf-metadata. - -.SH "ENVIRONMENT VARIABLES" - -.PP -Note that all command line options will override environment variables. -.PP - -.PP -.IP "BABELTRACE_VERBOSE" -Activate verbose Babeltrace output. -.PP -.IP "BABELTRACE_DEBUG" -Activate debug Babeltrace output. - -.SH "SEE ALSO" - -.PP -babeltrace-log(1), lttng(1), lttng-ust(3), lttng-sessiond(8) -.PP -.SH "BUGS" - -.PP -The lttng-live plugin does not honor the the "--output" command line -option. - -If you encounter any issues or usability problem, please report it on -our mailing list to help improve this -project. -.SH "CREDITS" - -Babeltrace and the babeltrace library are distributed under the MIT -license. See the files LICENSE and mit-license.txt for details. -.PP -A Web site is available at http://www.efficios.com/babeltrace for more -information on Babeltrace and the Common Trace Format. See -http://lttng.org for more information on the LTTng project. -.PP -Mailing list for support and development: . -.PP -You can find us on IRC server irc.oftc.net (OFTC) in #lttng. -.PP -.SH "THANKS" - -Thanks to the Linux Foundation and Ericsson for funding part of this -work. Thanks to the Multicore Association Tool Infrastructure Working -Group for their active role in the creation of the Common Trace Format. -.PP -.SH "AUTHORS" - -.PP -Babeltrace was originally written by Mathieu Desnoyers, with additional -contributions from various other people. It is currently maintained by -Mathieu Desnoyers . -.PP diff --git a/doc/debug-info.txt b/doc/debug-info.txt deleted file mode 100644 index 98ab1f68..00000000 --- a/doc/debug-info.txt +++ /dev/null @@ -1,189 +0,0 @@ -Babeltrace Debug Info Analysis ------------------------------ - -The babeltrace debug info analysis is a set of features which allow -mapping events from a trace to their location in source code or within -a binary file, based on their `ip` (instruction pointer) field. - -Prerequisites -------------- - -In order to install a version of babeltrace with debug info support, -the following libraries are required: - - * libelf - * libdw - -Both of them are provided by the elfutils project -(https://fedorahosted.org/elfutils/), and can be installed through the -elfutils package on Ubuntu, Debian, RHEL, and others. - -Compiling for Debug Info Analysis ---------------------------------- - -Traced programs on which debug info analysis is to be performed can be -compiled in a few different ways, and still lead to useful results. - -Ideally, one should compile the program in debug mode, which is -achieved on gcc by simply using the `-g` flag. This generates debug -information in the operating system's native format, which is then -used by babeltrace to map an event's source location to a file and -line number, and the name of the surrounding function. - -Do note that only debug information in DWARF format, version 2 or -later, is currently supported by babeltrace. Use the `-gdwarf` or -`-gdwarf-(VERSION)` to explicitly generate DWARF debug information. - -If the executable is not compiled with `-g` or an equivalent option -enabled, and thus no DWARF information is available, babeltrace will -use ELF symbols from the executable. Instead of providing source file, -line number and function name, however, the analysis will provide the -name of the nearest function symbol, plus an offset in bytes to the -location in the executable from which the event originated. - -If the executable has neither ELF symbols nor DWARF information, -babeltrace will be unable to map an event to its source location and -will simply display the instruction pointer (address), as in prior -versions of babeltrace. - -Getting the Right Tracer ------------------------- - -Debug info analysis is performed automatically by babeltrace, provided -the trace contains sufficient information. In order to be able to -trace all the necessary information, the following software is -required: - - * lttng-ust version 2.8.0 or later - * lttng-tools, corresponding version - -You can get these from source at: - - * https://github.com/lttng/lttng-ust - * https://github.com/lttng/lttng-tools - -Ubuntu users also have the option of installing via the LTTng daily -PPA: - - * https://launchpad.net/~lttng/+archive/ubuntu/daily - -Tracing for Debug Info Analysis -------------------------------- - -Babeltrace needs some extra information from contexts, namely ip and -vpid, to perform its analysis. These can be enabled after the creation -of a tracing session as follows: - - $ lttng add-context --userspace --type ip --type vpid - -The tracing can then be performed as it normally would. Once the trace -is collected, it can the be read by babeltrace for analysis. - -Analysing the Trace -------------------- - -To perform the analysis, the trace can simply be read as it normally -would: - - $ babeltrace - -Debug info analysis is on by default and will automatically print the -extra source location information if it can find it. A sample output -may look like this: - - [...] - [16:18:15.845829429] (+0.000011697) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D550E, debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9", src = "libhello.c:7" }, vpid = 28719 }, { my_string_field = "hello, tracer", my_integer_field = 42 } - [16:18:15.845841484] (+0.000012055) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D55E0, debug_info = { bin = "libhello.so+0x15e0", func = "bar+0xa9", src = "libhello.c:13" }, vpid = 28719 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 } - [16:18:15.845844852] (+0.000003368) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D56A5, debug_info = { bin = "libhello.so+0x16a5", func = "baz+0x9c", src = "libhello.c:20" }, vpid = 28719 }, { some_field = 1729 } - [...] - -The interesting part is the debug_info section of the context: - - debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9", src = "libhello.c:7" } - -This is the expected output for events generated by an executable for -which DWARF information is available. It shows the name of the binary -and offset to the tracepoint, the name of the function containing the -tracepoint instance which generated the event ("foo") and the offset -within the function, and its source location ("libhello.c", line 7). - -The second event in the sample output is of the same type -("my_first_tracepoint"), but it was generated by a different -tracepoint instance, hence the different source location (line 13) and -function ("bar"). - -The third event, of a different type, also shows debug information. - -If DWARF info is absent, but ELF symbols are not stripped, the output -will instead look like this: - - [...] - [16:18:15.845829429] (+0.000011697) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D550E, debug_info = { bin = "libhello.so+0x150e", func = "foo+0xa9" }, vpid = 28719 }, { my_string_field = "hello, tracer", my_integer_field = 42 } - [16:18:15.845841484] (+0.000012055) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D55E0, debug_info = { bin = "libhello.so+0x15e0", func = "bar+0xa9" }, vpid = 28719 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 } - [16:18:15.845844852] (+0.000003368) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F4D2A5D56A5, debug_info = { bin = "libhello.so+0x16a5", func = "baz+0x9c" }, vpid = 28719 }, { some_field = 1729 } - [...] - -The debug information now provides both binary and function location -information, but no source location information, as this requires -DWARF. The function names are in fact resolved using ELF symbols, so -there may be a discrepancy with those provided by DWARF (e.g. in the -case of mangling). - -Paths to the binary and to the source location (if any) can be -expanded by using the command-line option ---debug-info-full-path. Otherwise, only the filename is shown. - -Debug Info and Dynamic Loading ------------------------------- - -Babeltrace can resolve addresses of events originating from -dynamically loaded libraries, provided that some extra information is -collected at tracing time. - -This can be achieved by preloading LTTng UST's libdl helper when -launching the program to be traced, like so: - - $ LD_PRELOAD="liblttng-ust-dl.so" - -The tracing and analysis can now be performed as described in prior -sections, and events from tracepoints in dlopened libraries will be -resolved automatically by babeltrace. - -Separate Debug Info -------------------- - -It is possible to store DWARF debug information separate from an -executable, whether for concerns of file size, or simply to facilitate -the sharing of the debug information. - -This is usually achieved via one of two mechanisms, namely build ID -and debug link. Both methods permit separate executables and debug -information. Their use and operation is described in GDB's -documentation at: - - https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html - -Babeltrace will find separate debug files automatically, provided they -follow the requirements described in the documentation above. The -debug information lookup order is the same as GDB's, that is first -debug info is looked for within the executable, then through the build -ID method in the standard /usr/lib/debug/.build-id/ location, and -finally in the various possible debug link locations. The first debug -information file found is used. - -The --debug-info-dir command-line option can be used to override the -default /usr/lib/debug/ directory used in build ID and debug link -lookups. Multiple debug info directories are currently not supported. - -Target Prefix -------------- - -The debug info analysis uses the paths to the executables as collected -during tracing as one mechanism to resolve DWARF or ELF -information. If the trace was taken on a separate machine, for -instance, it is possible to use --debug-info-target-prefix to specify -a prefix directory, representing the root of the target filesystem, -which will then be used for lookups. For example, if an executable was -located at /usr/bin/foo on the target system, it could be placed at -/home/efficios/target/usr/bin/foo on the system on which the analysis -is performed. In this case, the prefix is /home/efficios/target/. diff --git a/doc/lttng-live.txt b/doc/lttng-live.txt deleted file mode 100644 index 2c2a072a..00000000 --- a/doc/lttng-live.txt +++ /dev/null @@ -1,27 +0,0 @@ -LTTNG LIVE ----------- - -This is a brief howto for using the Babeltrace with LTTng live protocol. -LTTng live allows the user to read a trace while it is running. - -In order to create a live LTTng session, please refer to the LTTng -documentation (version >= 2.4). - -Once the session is created and Babeltrace is installed, you can list the -sessions with : -$ babeltrace -i lttng-live net:// - -The output should look like this : -net://localhost/host/myhostname/mysessionname (timer = 1000000, 5 stream(s), 0 client(s) connected) - -It means that the session mysessionname on the host myhostname is currently -streaming its data to the relayd on localhost. - -To attach to this session and start receiving the trace : -$ babeltrace -i lttng-live net://localhost/host/myhostname/mysessionname - -You should now see trace data flowing in your console when events are produced. - -To report bugs, please use the same procedure as reporting bugs to Babeltrace, -but don't forget to add the -v to the commands above to provide enough debug -information. diff --git a/doc/man/.gitignore b/doc/man/.gitignore new file mode 100644 index 00000000..f54189ac --- /dev/null +++ b/doc/man/.gitignore @@ -0,0 +1,5 @@ +*.1 +*.7 +*.xml +*.html +asciidoc-attrs.conf diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am new file mode 100644 index 00000000..4c22e633 --- /dev/null +++ b/doc/man/Makefile.am @@ -0,0 +1,146 @@ +# Man pages are only built if they are enabled at configure time. +# +# They should always be built before creating a distribution tarball. + +# function which adds the source directory prefix and adds a given suffix +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 = +MAN1_NO_ASCIIDOC_NAMES = +MAN7_NO_ASCIIDOC_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 + +if ENABLE_DEBUG_INFO +MAN7_NO_ASCIIDOC_NAMES += \ + babeltrace-plugin-lttng-utils \ + babeltrace-filter.lttng-utils.debug-info +endif + +# AsciiDoc sources and outputs +MAN1_TXT = $(call manaddsuffix,.1.txt,$(MAN1_NAMES)) +MAN7_TXT = $(call manaddsuffix,.7.txt,$(MAN7_NAMES)) +MAN_TXT = $(MAN1_TXT) $(MAN7_TXT) +MAN_XML = $(patsubst $(srcdir)/%.txt,%.xml,$(MAN_TXT)) + +# common AsciiDoc source files +COMMON_TXT = \ + $(srcdir)/common-cli-env.txt \ + $(srcdir)/common-cli-files.txt \ + $(srcdir)/common-cmd-footer.txt \ + $(srcdir)/common-cmd-info-options.txt \ + $(srcdir)/common-cmd-params-format.txt \ + $(srcdir)/common-cmd-plugin-path.txt \ + $(srcdir)/common-common-compat-env.txt \ + $(srcdir)/common-ctf-plugin-env.txt \ + $(srcdir)/common-footer.txt \ + $(srcdir)/common-gen-options.txt \ + $(srcdir)/common-lib-env.txt \ + $(srcdir)/common-plugin-path-options.txt \ + $(srcdir)/common-ppp-env.txt + +# config +ASCIIDOC_CONF = $(srcdir)/bt-asciidoc.conf +ASCIIDOC_ATTRS_CONF = $(builddir)/asciidoc-attrs.conf +XSL_SRC_FILE = $(srcdir)/manpage.xsl + +# common dependencies +COMMON_DEPS = $(ASCIIDOC_CONF) $(COMMON_TXT) + +# man pages destinations +MAN1 = $(addsuffix .1,$(MAN1_NAMES)) +MAN7 = $(addsuffix .7,$(MAN7_NAMES)) +MAN1_NO_ASCIIDOC = $(addsuffix .1,$(MAN1_NO_ASCIIDOC_NAMES)) +MAN7_NO_ASCIIDOC = $(addsuffix .7,$(MAN7_NO_ASCIIDOC_NAMES)) +MAN = $(MAN1) $(MAN7) + +if ENABLE_MAN_PAGES +# at this point, we know the user asked to build the man pages +if HAVE_ASCIIDOC_XMLTO +asciidoc_verbose = $(asciidoc_verbose_@AM_V@) +asciidoc_verbose_ = $(asciidoc_verbose_@AM_DEFAULT_V@) +asciidoc_verbose_0 = @echo " ASCIIDOC " $@; +xmlto_verbose = $(xmlto_verbose_@AM_V@) +xmlto_verbose_ = $(xmlto_verbose_@AM_DEFAULT_V@) +xmlto_verbose_0 = @echo " XMLTO " $@; + +# tools +ADOC = $(asciidoc_verbose)$(ASCIIDOC) -f $(ASCIIDOC_CONF) -f $(ASCIIDOC_ATTRS_CONF) -d manpage +ADOC_DOCBOOK = $(ADOC) -b docbook +XTO = $(xmlto_verbose)$(XMLTO) -m $(XSL_SRC_FILE) man + +# only add this dependency if we can build the man pages because it's +# a file generated by the configure script, so it's more recent than +# the pregenerated man pages in a tarball +COMMON_DEPS += $(ASCIIDOC_ATTRS_CONF) + +# recipes +%.1.xml: $(srcdir)/%.1.txt $(COMMON_DEPS) + $(ADOC_DOCBOOK) -o $@ $< + +%.1: %.1.xml $(XSL_SRC_FILE) + $(XTO) $< 2>/dev/null + +%.7.xml: $(srcdir)/%.7.txt $(COMMON_DEPS) + $(ADOC_DOCBOOK) -o $@ $< + +%.7: %.7.xml $(XSL_SRC_FILE) + $(XTO) $< 2>/dev/null + +# only clean the generated files if we have the tools to generate them again +CLEANFILES = $(MAN_XML) $(MAN) +else # HAVE_ASCIIDOC_XMLTO +# create man page targets used to stop the build if we want to +# build the man pages, but we don't have the necessary tools to do so +ERR_MSG = "Error: Cannot build target because asciidoc or xmlto tool is missing." +ERR_MSG += "Make sure both tools are installed and run the configure script again." + +%.1: $(srcdir)/%.1.txt $(COMMON_DEPS) + @echo $(ERR_MSG) + @false + +%.7: $(srcdir)/%.7.txt $(COMMON_DEPS) + @echo $(ERR_MSG) + @false +endif # HAVE_ASCIIDOC_XMLTO +endif # ENABLE_MAN_PAGES + +# those are always installed since they are directly written in troff +dist_man1_MANS = $(MAN1_NO_ASCIIDOC) +dist_man7_MANS = $(MAN7_NO_ASCIIDOC) + +if ENABLE_MAN_PAGES +# building man pages: we can install and distribute them +dist_man1_MANS += $(MAN1) +dist_man7_MANS += $(MAN7) +endif # ENABLE_MAN_PAGES + +if !ENABLE_MAN_PAGES +dist-hook: + @echo "Error: Please enable the man pages before creating a distribution tarball." + @false +endif # !ENABLE_MAN_PAGES + +# always distribute the source files +EXTRA_DIST = README.adoc $(MAN_TXT) $(COMMON_TXT) $(XSL_SRC_FILE) \ + $(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in diff --git a/doc/man/README.adoc b/doc/man/README.adoc new file mode 100644 index 00000000..1fc3bb07 --- /dev/null +++ b/doc/man/README.adoc @@ -0,0 +1,136 @@ += Babeltrace man pages +Philippe Proulx +4 October 2017 + +This directory contains the sources of the Babeltrace man pages. + +The Babeltrace man pages are written in +http://www.methods.co.nz/asciidoc/[AsciiDoc], and then converted to +DocBook (XML) using the `asciidoc` command, and finally to troff using +the appropriate DocBook XSL stylesheet (using the `xmlto` command). + + +== Naming + +Main program:: + +__program__.1.txt+ + +`babeltrace(1)` command:: + +babeltrace-__command__.1.txt+ + +Babeltrace introduction:: + `babeltrace-intro.7.txt` + +Babeltrace plugin:: + +babeltrace-plugin-__plugin__.7.txt+ + +Babeltrace plugin's component class:: + +babeltrace-__type__.__plugin__.__compcls__.7.txt+ + + +== Macros + +AsciiDoc is configured with `bt-asciidoc.conf` which contains a few +macro definitions used everywhere in the man page sources: + ++man:__page__(__section__)+:: + Use this macro to insert a link to another man page named + +__page__+ in section +__section__+. In troff, the man page's name + is rendered in bold. ++ +Example: `man:babeltrace-convert(1)` + ++opt:__name__+:: + Use this macro to insert a link to the command-line option + +__name__+ described in an _OPTIONS_ section in the same man page. ++ +Example: `opt:--verbose`, `opt:--color='WHEN'` + ++manopt:__page__(__section__):__name__+:: + Use this macro to insert a link to the command-line option + +__name__+ described in the _OPTIONS_ section of another Babeltrace + or LTTng man page named +__page__+ in section +__section__+. ++ +Example: `manopt:babeltrace(1):--log-level`, ++manopt:babeltrace-convert(1):--component=\`source.ctf.fs`+ + ++nlopt:__name__+:: + Use this macro to write a command-line option named +__name__+ + without inserting a link. The option does not need to be described + in the same man page. ++ +Example: `nlopt:--help` + ++param:__name__+:: + Use this macro to insert a link to the component initialization + parameter named +__name__+ described in an _INITIALIZATION + PARAMETERS_ section in the same man page. ++ +Example: `param:begin`, `param:path='PATH'` + ++manparam:__type__.__plug__.__compclsname__:__paramname__+:: + Use this macro to insert a link to the component initialization + parameter +__paramname__+ described in the _INITIALIZATION + PARAMETERS_ section of the man page of another Babeltrace component + class. The component class has the type +__type__+, is found in the + plugin named +__plug__+ and is named +__name__+. ++ +Example: `manparam:filter.utils.trimmer:begin`, +`manparam:source.ctf.fs:path` + ++nlparam:__name__+:: + Use this macro to write a component initialization parameter named + +__name__+ without inserting a link. The parameter does not need to + be described in the same man page. ++ +Example: `nlparam:end` + ++compcls:__type__.__plug__.__name__+:: + Use this macro to write a component class specification. The + component class has the type +__type__+, is found in the plugin + named +__plug__+ and is named +__name__+. ++ +Example: `compcls:source.ctf.fs`, `compcls:filter.utils.muxer` + +`:not:`:: + Use `:not:` to emphasize _not_. + +`:escstar:`:: + Use `:escstar:` to insert `\*` literally. + +`:esccomma:`:: + Use `:esccomma:` to insert `\,` literally. + +`:escdot:`:: + Use `:escdot:` to insert `\.` literally. + + +== Attributes + +`manpagetype`:: + Each man page must set this attribute to the type (lowercase) of the + man page: `program`, `command`, `plugin`, or `component class`. It's + used in various included files to output a text that is more + targeted. + +`revdate`:: + Each man page should have its own revision date with the following + https://en.wikipedia.org/wiki/Date_and_time_notation_in_the_United_Kingdom[British format]: + _28 October 1987_. ++ +Make sure to update this date when you update a given man page. We are +not generating the date automatically because we want the real last +revision date in the man page, not the last build date. + +Also see `asciidoc-attrs.conf` which is generated by `config.status` +from `asciidoc-attrs.conf.in`. This file contains fixed and +configuration-dependent attributes which you can use anywhere in the +sources. + + +== Style + +Apply the recommendations of the +link:https://github.com/lttng/lttng-docs/blob/master/CONTRIBUTING.adoc#style-considerations[_Style +considerations_] section of the LTTng Documentation's contributor's +guide. diff --git a/doc/man/asciidoc-attrs.conf.in b/doc/man/asciidoc-attrs.conf.in new file mode 100644 index 00000000..a5ece768 --- /dev/null +++ b/doc/man/asciidoc-attrs.conf.in @@ -0,0 +1,5 @@ +[attributes] +# default values +system_plugin_path="@LIBDIR@/babeltrace/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 new file mode 100644 index 00000000..8f4aff1a --- /dev/null +++ b/doc/man/babeltrace-convert.1.txt @@ -0,0 +1,999 @@ +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-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:--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 \ + --key=path --value=/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 \ + --key=path --value=/path/to/input/trace \ + --component=sink-ctf-fs:sink.ctf.fs \ + --key=path --value=out-dir \ + --component=muxer:flt.utils.muxer \ + --component=trimmer:flt.utils.trimmer \ + --key=begin --value=22:14:38 \ + --key=end --value=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':: + 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 new file mode 100644 index 00000000..08820296 --- /dev/null +++ b/doc/man/babeltrace-filter.lttng-utils.debug-info.7.txt @@ -0,0 +1,238 @@ +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. + +The filter component needs the LTTng-UST events to contain the +`ip` and `vpid` fields in their context. + +To add those context fields with the man:lttng(1) command-line tool +before the tracers are active (before `lttng start`): + +[role="term"] +---- +$ lttng add-context --userspace --type=ip --type=vpid +---- + +See man:lttng-add-context(1) for more information. + +To get debugging information for LTTng-UST events which occur in +dynamically loaded objects, for example plugins, start the application +to trace with the LTTng-UST dynamic linking helper: + +[role="term"] +---- +$ LD_PRELOAD=liblttng-ust-dl.so my-app +---- + +See man:lttng-ust-dl(3) for more information. + + +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 new file mode 100644 index 00000000..b35731fc --- /dev/null +++ b/doc/man/babeltrace-filter.utils.muxer.7.txt @@ -0,0 +1,86 @@ +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 new file mode 100644 index 00000000..97f627d8 --- /dev/null +++ b/doc/man/babeltrace-filter.utils.trimmer.7.txt @@ -0,0 +1,125 @@ +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 new file mode 100644 index 00000000..13b06b3e --- /dev/null +++ b/doc/man/babeltrace-help.1.txt @@ -0,0 +1,94 @@ +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 new file mode 100644 index 00000000..101fe7a4 --- /dev/null +++ b/doc/man/babeltrace-intro.7.txt @@ -0,0 +1,415 @@ +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 new file mode 100644 index 00000000..f15e9760 --- /dev/null +++ b/doc/man/babeltrace-list-plugins.1.txt @@ -0,0 +1,51 @@ +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 new file mode 100644 index 00000000..2f87ac54 --- /dev/null +++ b/doc/man/babeltrace-log.1.txt @@ -0,0 +1,75 @@ +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 new file mode 100644 index 00000000..4749104d --- /dev/null +++ b/doc/man/babeltrace-plugin-ctf.7.txt @@ -0,0 +1,49 @@ +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 new file mode 100644 index 00000000..fd946f8a --- /dev/null +++ b/doc/man/babeltrace-plugin-lttng-utils.7.txt @@ -0,0 +1,38 @@ +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 new file mode 100644 index 00000000..36eee2c5 --- /dev/null +++ b/doc/man/babeltrace-plugin-text.7.txt @@ -0,0 +1,44 @@ +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 new file mode 100644 index 00000000..e1a0a6be --- /dev/null +++ b/doc/man/babeltrace-plugin-utils.7.txt @@ -0,0 +1,60 @@ +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 new file mode 100644 index 00000000..f15e69bf --- /dev/null +++ b/doc/man/babeltrace-query.1.txt @@ -0,0 +1,128 @@ +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 new file mode 100644 index 00000000..802846c8 --- /dev/null +++ b/doc/man/babeltrace-run.1.txt @@ -0,0 +1,400 @@ +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'. + +opt:--key='KEY' followed with opt:--value='VALUE':: + Set the current component's initialization parameter named 'KEY' to + the string value 'VALUE'. If 'KEY' exists in the current component's + initialization parameters, the parameter is replaced. + + +[[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:--key='KEY':: + Set the current parameter key to 'KEY'. The next opt:--value option + uses this key to add a parameter to the current component. + +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. + +opt:-v 'VALUE', opt:--value='VALUE':: + Add a parameter to the current component's initialization parameters + of which the key is the argument of the last opt:--key option and + the string value is 'VALUE'. If the current component's + initialization parameters already contain a key named 'KEY', replace + the parameter. + + +Component connection +~~~~~~~~~~~~~~~~~~~~ +opt:-C '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:--key and opt:--value options to set a current component's initialization parameter. +==== +[role="term"] +---- +$ babeltrace run --component=the-source:src.my-plugin.my-src \ + --key=path --value ~/my-traces/the-trace + --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 new file mode 100644 index 00000000..bd04246e --- /dev/null +++ b/doc/man/babeltrace-sink.ctf.fs.7.txt @@ -0,0 +1,115 @@ +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 new file mode 100644 index 00000000..8a3629d7 --- /dev/null +++ b/doc/man/babeltrace-sink.text.pretty.7.txt @@ -0,0 +1,147 @@ +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 new file mode 100644 index 00000000..008c9277 --- /dev/null +++ b/doc/man/babeltrace-sink.utils.counter.7.txt @@ -0,0 +1,87 @@ +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 new file mode 100644 index 00000000..9173cd34 --- /dev/null +++ b/doc/man/babeltrace-sink.utils.dummy.7.txt @@ -0,0 +1,57 @@ +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 new file mode 100644 index 00000000..74b08b67 --- /dev/null +++ b/doc/man/babeltrace-source.ctf.fs.7.txt @@ -0,0 +1,258 @@ +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 new file mode 100644 index 00000000..fc2803d3 --- /dev/null +++ b/doc/man/babeltrace-source.ctf.lttng-live.7.txt @@ -0,0 +1,187 @@ +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 new file mode 100644 index 00000000..a3183388 --- /dev/null +++ b/doc/man/babeltrace-source.text.dmesg.7.txt @@ -0,0 +1,80 @@ +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 new file mode 100644 index 00000000..cd05dbf6 --- /dev/null +++ b/doc/man/babeltrace.1.txt @@ -0,0 +1,187 @@ +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:--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/bt-asciidoc.conf b/doc/man/bt-asciidoc.conf new file mode 100644 index 00000000..c7611d08 --- /dev/null +++ b/doc/man/bt-asciidoc.conf @@ -0,0 +1,195 @@ +[macros] + +# command-line option in another man page macro +# +# Usage: manopt:page(section):--option-name +(?su)[\\]?(?Pmanopt):(?P[a-zA-Z0-9_.-]+)\((?P
[a-zA-Z0-9]+)\):(?P--?[a-zA-Z0-9-]*)= + +# component class initialization parameter in another man page macro +# +# Usage: manparam:type.plugin.compcls:param-name +(?su)[\\]?(?Pmanparam):(?P[a-zA-Z0-9_-]+)\.(?P[a-zA-Z0-9_-]+)\.(?P[a-zA-Z0-9_-]+):(?P[a-zA-Z0-9_:.-]+(?man):(?P[a-zA-Z0-9_.-]+)\((?P
[a-zA-Z0-9]+)\)= + +# no link option macro +# +# Usage: nlopt:--option-name +(?su)[\\]?(?Pnlopt):(?P--?[a-zA-Z0-9-]*)= + +# command-line option macro +# +# Usage: opt:--option-name +(?su)[\\]?(?Popt):(?P--?[a-zA-Z0-9-]*)= + +# no link component class initialization parameter macro +# +# Usage: nlparam:param-name +(?su)[\\]?(?Pnlparam):(?P[a-zA-Z0-9_:.-]+(?param):(?P[a-zA-Z0-9_:.-]+(?compcls):(?P[a-zA-Z0-9_-]+)\.(?P[a-zA-Z0-9_-]+)\.(?P[a-zA-Z0-9_-]+)= + +# not macro +# +# Usage: :not: +:not:=not + +# escstar macro +# +# Usage: :escstar: +:escstar:=escstar + +# esccomma macro +# +# Usage: :esccomma: +:esccomma:=esccomma + +# escdot macro +# +# Usage: :escdot: +:escdot:=escdot + +# bs macro +# +# Usage: :bs: +:bs:=bs + +# man macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[man-inlinemacro] + +{target}{section} + +endif::backend-docbook[] +endif::doctype-manpage[] + +# no link option macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[nlopt-inlinemacro] +{opt} +endif::backend-docbook[] +endif::doctype-manpage[] + +# command-line option macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[opt-inlinemacro] +{opt} +endif::backend-docbook[] +endif::doctype-manpage[] + +# command-line option in another man page macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[manopt-inlinemacro] +{opt} +endif::backend-docbook[] +endif::doctype-manpage[] + +# component class initialization parameter macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[param-inlinemacro] +{pname} +endif::backend-docbook[] +endif::doctype-manpage[] + +# no link component class initialization parameter macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[nlparam-inlinemacro] +{pname} +endif::backend-docbook[] +endif::doctype-manpage[] + +# component class initialization parameter in another man page macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[manparam-inlinemacro] +{pname} +endif::backend-docbook[] +endif::doctype-manpage[] + +# component class specification macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[compcls-inlinemacro] +{cctype}.{ccplug}.{ccname} +endif::backend-docbook[] +endif::doctype-manpage[] + +# not macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[not-inlinemacro] +NOT +endif::backend-docbook[] +endif::doctype-manpage[] + +# escstar macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[escstar-inlinemacro] +\e* +endif::backend-docbook[] +endif::doctype-manpage[] + +# esccomma macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[esccomma-inlinemacro] +\e, +endif::backend-docbook[] +endif::doctype-manpage[] + +# escdot macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[escdot-inlinemacro] +\e, +endif::backend-docbook[] +endif::doctype-manpage[] + +# bs macro expansions +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[bs-inlinemacro] +\e +endif::backend-docbook[] +endif::doctype-manpage[] + +# configure XML man page header +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + + {revdate} + + + {mantitle} + {manvolnum} + Babeltrace + {babeltrace_version} + Babeltrace manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] diff --git a/doc/man/common-cli-env.txt b/doc/man/common-cli-env.txt new file mode 100644 index 00000000..85140e8e --- /dev/null +++ b/doc/man/common-cli-env.txt @@ -0,0 +1,16 @@ +ENVIRONMENT VARIABLES +--------------------- +include::common-lib-env.txt[] + +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. + +`BABELTRACE_CLI_WARN_COMMAND_NAME_DIRECTORY_CLASH`:: + Set to `0` to disable the warning message which `babeltrace` prints + when you convert a trace with a relative path that's also the name + of a `babeltrace` command. diff --git a/doc/man/common-cli-files.txt b/doc/man/common-cli-files.txt new file mode 100644 index 00000000..c2451a16 --- /dev/null +++ b/doc/man/common-cli-files.txt @@ -0,0 +1,7 @@ +FILES +----- +`$HOME/.local/lib/babeltrace/plugins`:: + User plugin directory. + ++{system_plugin_path}+:: + System plugin directory. diff --git a/doc/man/common-cmd-footer.txt b/doc/man/common-cmd-footer.txt new file mode 100644 index 00000000..b1967305 --- /dev/null +++ b/doc/man/common-cmd-footer.txt @@ -0,0 +1,6 @@ +EXIT STATUS +----------- +*0* on success, *1* otherwise. + + +include::common-footer.txt[] diff --git a/doc/man/common-cmd-info-options.txt b/doc/man/common-cmd-info-options.txt new file mode 100644 index 00000000..ecc1041e --- /dev/null +++ b/doc/man/common-cmd-info-options.txt @@ -0,0 +1,4 @@ +Command information +~~~~~~~~~~~~~~~~~~~ +opt:-h, opt:--help:: + Show the command's help and quit. diff --git a/doc/man/common-cmd-params-format.txt b/doc/man/common-cmd-params-format.txt new file mode 100644 index 00000000..c3ee8d4f --- /dev/null +++ b/doc/man/common-cmd-params-format.txt @@ -0,0 +1,48 @@ +[[params-fmt]] +Parameters format +~~~~~~~~~~~~~~~~~ +The format of the 'PARAMS' option's argument is a comma-separated +list of `NAME=VALUE` assignments: + +[verse] +'NAME'='VALUE'[,'NAME'='VALUE']... + +'NAME':: + Parameter name (C{nbsp}identifier plus the `:`, `.`, and `-` characters). + +'VALUE':: + One of: ++ +-- +* `null`, `nul`, `NULL`: null value. + +* `true`, `TRUE`, `yes`, `YES`: true boolean value. + +* `false`, `FALSE`, `no`, `NO`: false boolean value. + +* Binary (`0b` prefix), octal (`0` prefix), decimal, or hexadecimal + (`0x` prefix) signed 64-bit integer. + +* Double precision floating point number (scientific notation is + accepted). + +* Unquoted string with no special characters, and not matching any of + the null and boolean value symbols above. + +* Double-quoted string (accepts escape characters). + +You may put whitespaces around the individual `=` (assignment) and `,` +(separator) characters. +-- + +Example: + +---- +babeltrace ... --params='many=null, fresh=yes, condition=false, + squirrel=-782329, observe=3.14, + simple=beef, needs-quotes="some string", + escape.chars-are:allowed="a \" quote"' +---- + +IMPORTANT: Like in the example above, make sure to single-quote the +whole argument when you run this command from a shell. diff --git a/doc/man/common-cmd-plugin-path.txt b/doc/man/common-cmd-plugin-path.txt new file mode 100644 index 00000000..ae8afc3d --- /dev/null +++ b/doc/man/common-cmd-plugin-path.txt @@ -0,0 +1,19 @@ +Plugin path +~~~~~~~~~~~ +This command loads Babeltrace plugins to perform its operation. The +search path for Babeltrace plugins is, in this order: + +. The colon-separated list of directories in the + `BABELTRACE_PLUGIN_PATH` environment variable. + +. The colon-separated list of directories in the opt:--plugin-path + option. + +. *If the opt:--omit-home-plugin-path option is absent*: + `$HOME/.local/lib/babeltrace/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 +list the available plugins. diff --git a/doc/man/common-common-compat-env.txt b/doc/man/common-common-compat-env.txt new file mode 100644 index 00000000..ee17f8f2 --- /dev/null +++ b/doc/man/common-common-compat-env.txt @@ -0,0 +1,23 @@ +`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). + +`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). + +`BABELTRACE_TERM_COLOR`:: + Force the terminal color support. The available values are: ++ +-- +`AUTO`:: + Only emit terminal color codes when the standard output and error + streams are connected to a color-capable terminal. + +`NEVER`:: + Never emit terminal color codes. + +`ALWAYS`:: + Always emit terminal color codes. +-- diff --git a/doc/man/common-ctf-plugin-env.txt b/doc/man/common-ctf-plugin-env.txt new file mode 100644 index 00000000..a4ecb483 --- /dev/null +++ b/doc/man/common-ctf-plugin-env.txt @@ -0,0 +1,16 @@ +`ctf` plugin +~~~~~~~~~~~~ +`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). + +`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). + +`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). diff --git a/doc/man/common-footer.txt b/doc/man/common-footer.txt new file mode 100644 index 00000000..7cbe6956 --- /dev/null +++ b/doc/man/common-footer.txt @@ -0,0 +1,36 @@ +BUGS +---- +If you encounter any issue or usability problem, please report it on the +https://bugs.linuxfoundation.org/buglist.cgi?product=Diamon&component=Babeltrace[Babeltrace +bug tracker]. + + +RESOURCES +--------- +The Babeltrace project shares some communication channels with the +http://lttng.org/[LTTng project]. + +* http://diamon.org/babeltrace[Babeltrace website] +* http://git.linuxfoundation.org/?p=diamon/babeltrace.git[Git repository] +* http://github.com/efficios/[EfficiOS GitHub organization] +* https://ci.lttng.org/job/babeltrace_master_build/[Continuous integration] +* http://lists.lttng.org[Mailing list] for support and + development: `lttng-dev@lists.lttng.org` +* irc://irc.oftc.net/lttng[IRC channel]: `#lttng` on `irc.oftc.net` + + +AUTHORS +------- +The Babeltrace project is the result of efforts by many regular +developers and occasional contributors. + +The current project maintainer is +mailto:jeremie.galarneau@efficios.com[Jérémie Galarneau]. + + +COPYRIGHT +--------- +This {manpagetype} is part of the Babeltrace project. + +Babeltrace is distributed under the +https://opensource.org/licenses/MIT[MIT license]. diff --git a/doc/man/common-gen-options.txt b/doc/man/common-gen-options.txt new file mode 100644 index 00000000..58b3b09b --- /dev/null +++ b/doc/man/common-gen-options.txt @@ -0,0 +1,18 @@ +General options +~~~~~~~~~~~~~~~ +See man:babeltrace(1) for more details. + +nlopt:-d, nlopt:--debug:: + Turn the debugging mode on. + +nlopt:--log-level='LVL':: + Set the log level of all known Babeltrace loggers to 'LVL'. + +nlopt:-v, nlopt:--verbose:: + Turn the verbose mode on. + +nlopt:-h, nlopt:--help:: + Show general help and quit. + +nlopt:-V, nlopt:--version:: + Show version and quit. diff --git a/doc/man/common-lib-env.txt b/doc/man/common-lib-env.txt new file mode 100644 index 00000000..179c98d3 --- /dev/null +++ b/doc/man/common-lib-env.txt @@ -0,0 +1,20 @@ +Babeltrace library +~~~~~~~~~~~~~~~~~~ +include::common-common-compat-env.txt[] + +`BABELTRACE_DISABLE_PYTHON_PLUGINS`:: + Set to `1` to disable the loading of any Babeltrace Python plugin. + +`BABELTRACE_LOGGING_GLOBAL_LEVEL`:: + Babeltrace library's global log level. The available values are the + same as for the manopt:babeltrace(1):--log-level option of + man:babeltrace(1) + +`BABELTRACE_NO_DLCLOSE`:: + Set to `1` to make the Babeltrace library leave any dynamically + loaded modules (plugins and Python plugin provider) open at exit. + This can be useful for debugging purposes. + +`BABELTRACE_PLUGIN_PATH`:: + Colon-separated list of directories, in order, in which dynamic + plugins can be found before other directories are considered. diff --git a/doc/man/common-plugin-path-options.txt b/doc/man/common-plugin-path-options.txt new file mode 100644 index 00000000..446ab003 --- /dev/null +++ b/doc/man/common-plugin-path-options.txt @@ -0,0 +1,11 @@ +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. diff --git a/doc/man/common-ppp-env.txt b/doc/man/common-ppp-env.txt new file mode 100644 index 00000000..f2fa3539 --- /dev/null +++ b/doc/man/common-ppp-env.txt @@ -0,0 +1,6 @@ +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). diff --git a/doc/man/manpage.xsl b/doc/man/manpage.xsl new file mode 100644 index 00000000..da5b3235 --- /dev/null +++ b/doc/man/manpage.xsl @@ -0,0 +1,43 @@ + + + + + + + + + sp + + + + + + + + br + + + + + + + + <> + + + (see <>) + + + + + + + \fB + + \fR + + + + 0 +