--- /dev/null
+babeltrace2-filter.lttng-utils.debug-info(7)
+===========================================
+:manpagetype: component class
+:revdate: 5 October 2017
+:comp: compcls:filter.lttng-utils.debug-info
+:defdebuginfoname: `debug_info`
+
+
+NAME
+----
+babeltrace2-filter.lttng-utils.debug-info - Babeltrace's debugging
+information filter component class for LTTng traces
+
+
+DESCRIPTION
+-----------
+The Babeltrace {comp} component class, provided by the the
+man:babeltrace2-plugin-lttng-utils(7) plugin, once instantiated, receives
+events from http://lttng.org/[LTTng] traces and creates new ones
+which are copies of the original ones with extra debugging information
+when it's available and possible.
+
+A {comp} component uses the LTTng state dump events as well as the event
+context's `ip` (instruction pointer) field to locate and read the
+corresponding debugging information. The component can find the extra
+debugging information in an executable file or in a directory containing
+debugging information created by the compiler.
+
+The new events contain the exact same fields as the original ones and,
+when possible, a new event context's structure field (besides the `ip`
+field) named {defdebuginfoname} by default. This structure field
+contains the following fields:
+
+`bin` (string field)::
+ Executable path or name followed by `@ADDR` or `+ADDR`, where
+ `ADDR` is the address where it was loaded while being traced.
+ `@ADDR` means `ADDR` is an absolute address, and `+ADDR` means
+ `ADDR` is a relative address.
++
+Example: `my-program@0x401040`.
+
+[[field-func]]`func` (string field)::
+ Function name followed by `+OFFSET`, where `OFFSET` is the
+ offset from the beginning of the function symbol in the executable
+ file.
++
+Example: `load_user_config+0x194`.
+
+[[field-src]]`src` (string field)::
+ Source file path or name followed by `:LINE`, where `LINE` is the
+ line number in this source file at which the event occured.
++
+Example: `user-config.c:1025`.
+
+Any of those the previous fields can be an empty string if the
+debugging information was not available for the analyzed original
+LTTng event.
+
+When a filter component creates a new event with debugging
+information, it discards the original event. If the component receives a
+non-LTTng event, the component moves the event to its output port
+without alteration.
+
+
+Compile an executable for debugging information analysis
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+With GCC or Clang, you should compile the program or library source
+files in debug mode with the nlopt:-g option. This option makes the
+compiler generate debugging information in the operating system's native
+format. This format is recognized by a {comp} component: it can
+translate the instruction pointer field of an event's context to a
+source file and line number, along with the name of the surrounding
+function.
+
+NOTE: This component class only supports the debugging information in
+DWARF format, version{nbsp}2 or later. Use the nlopt:-gdwarf or
+nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler
+options to explicitly generate DWARF debugging information.
+
+If you don't compile the executable's source files with the nlopt:-g
+option or with an equivalent option, no DWARF information is available:
+the component uses ELF symbols from the executable file instead. In this
+case, the events that the component creates do not contain the source
+file and line number (<<field-src,`src` field>>), but only the name of
+the nearest function symbol with an offset in bytes to the location in
+the executable from which the LTTng event occured (<<field-func,`func`
+field>>).
+
+If the executable file has neither ELF symbols nor DWARF information,
+the {comp} component cannot map the event to
+its source location: it emits the original LTTng event which has no
+special {defdebuginfoname} context field.
+
+
+LTTng prerequisites
+~~~~~~~~~~~~~~~~~~~
+A {comp} component can only analyze user space events generated by
+http://lttng.org[LTTng]{nbsp}2.8.0 or later.
+
+To get debugging information for LTTng-UST events which occur in
+executables and libraries which the system's loader loads (what
+you can see with man:ldd(1)):
+
+. Add the `ip` and `vpid` context fields to user space event records:
++
+--
+[role="term"]
+----
+$ lttng add-context --userspace --type=ip --type=vpid
+----
+--
++
+See man:lttng-add-context(1) for more details.
+
+. Enable the LTTng-UST state dump events:
++
+--
+[role="term"]
+----
+$ lttng enable-event --userspace 'lttng_ust_statedump:*'
+----
+--
++
+See man:lttng-enable-event(1) and man:lttng-ust(3) for more details.
+
+To get debugging information for LTTng-UST events which occur in
+dynamically loaded objects, for example plugins:
+
+. Do the previous steps (add context fields and enable
+ the LTTng-UST state dump events).
+
+. Enable the LTTng-UST dynamic linker tracing helper events:
++
+--
+[role="term"]
+----
+$ lttng enable-event --userspace 'lttng_ust_dl:*'
+----
+--
++
+See man:lttng-ust-dl(3) for more details.
+
+. When you are ready to trace, start your application with the
+ `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`:
++
+--
+[role="term"]
+----
+$ LD_PRELOAD=liblttng-ust-dl.so my-app
+----
+--
+
+
+Separate debugging information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It is possible to store DWARF debugging information outside the
+executable itself, whether it is to reduce the executable's file size,
+or simply to facilitate the sharing of the debugging information.
+
+This is usually achieved via one of two mechanisms, namely _build ID_
+and _debug link_. Their use and operation is described in the
+https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging
+Information in Separate Files] section of GDB's documentation.
+
+A {comp} component can find separate debugging information files
+automatically, as long as they meet the requirements stated in this man
+page.
+
+The debugging information lookup order is the same as GDB's, namely:
+
+. Within the executable file itself.
+
+. Through the build ID method in the `/usr/lib/debug/.build-id`
+ directory.
+
+. In the various possible debug link locations.
+
+The component uses the first debugging information file that it finds.
+
+You can use the param:deubg-info-dir initialization parameter to
+override the default `/usr/lib/debug` directory used in the build ID and
+debug link methods.
+
+NOTE: It is currently not possible to make this component search for
+debugging information in multiple directories.
+
+
+Target prefix
+~~~~~~~~~~~~~
+The debugging information analysis that a {comp} component performs uses
+the paths to the executables as collected during tracing as the default
+mechanism to resolve DWARF and ELF information.
+
+If the trace was recorded on a separate machine, however, you can use
+the param:target-prefix parameter to specify a prefix directory, that
+is, the root of the target file system.
+
+For example, if an instrumented executable's path is `/usr/bin/foo` on
+the target system, you can place this file at
+`/home/user/target/usr/bin/foo` on the system on which you use the
+component. In this case, the target prefix to use is
+`/home/user/target`.
+
+
+INITIALIZATION PARAMETERS
+-------------------------
+The following parameters are optional.
+
+param:debug-info-dir='DIR' (string)::
+ Use 'DIR' as the directory from which to load debugging information
+ with the build ID and debug link methods instead of
+ `/usr/lib/debug`.
+
+param:debug-info-field-name='NAME' (string)::
+ Name the debugging information structure field in the context of
+ the created events 'NAME' instead of the default {defdebuginfoname}.
+
+param:full-path=`yes` (boolean)::
+ Use the full path when writing the executable name (`bin`) and
+ source file name (`src`) fields in the {defdebuginfoname} context
+ field of the created events.
+
+param:target-prefix='DIR' (string)::
+ Use 'DIR' as the root directory of the target file system instead of
+ `/`.
+
+
+PORTS
+-----
+Input
+~~~~~
+`in`::
+ Single input port from which the component receives the
+ notifications to augment with debugging information.
+
+
+Output
+~~~~~~
+`out`::
+ Single output port to which the component sends the augmented
+ or unaltered notifications.
+
+
+QUERY OBJECTS
+-------------
+This component class has no objects to query.
+
+
+ENVIRONMENT VARIABLES
+---------------------
+include::common-common-compat-env.txt[]
+
+`BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`::
+ Component class's log level. The available values are the
+ same as for the manopt:babeltrace2(1):--log-level option of
+ man:babeltrace2(1).
+
+
+include::common-footer.txt[]
+
+
+SEE ALSO
+--------
+man:babeltrace2-plugin-lttng-utils(7),
+man:lttng(1),
+man:lttng-add-context(1),
+man:babeltrace2-intro(7)
projects / babeltrace.git / blobdiff