NAME | DESCRIPTION | INITIALIZATION PARAMETERS | PORTS | QUERY OBJECTS | ENVIRONMENT VARIABLES | BUGS | RESOURCES | AUTHORS | COPYRIGHT | SEE ALSO | COLOPHON

BABELTRACE-FILTER(7)          Babeltrace manual         BABELTRACE-FILTER(7)

NAME         top

       babeltrace-filter.lttng-utils.debug-info - Babeltrace's debugging
       information filter component class for LTTng traces

DESCRIPTION         top

       The Babeltrace filter.lttng-utils.debug-info component class,
       provided by the the babeltrace-plugin-lttng-utils(7) plugin, once
       instantiated, receives events from LTTng (see <http://lttng.org/>)
       traces and creates new ones which are copies of the original ones
       with extra debugging information when it’s available and possible.

       A filter.lttng-utils.debug-info 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 debug_info 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.

       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.

       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 -g option. This option makes the
       compiler generate debugging information in the operating system’s
       native format. This format is recognized by a filter.lttng-
       utils.debug-info 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 2 or later. Use the -gdwarf or -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 -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 (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 (func field).

       If the executable file has neither ELF symbols nor DWARF information,
       the filter.lttng-utils.debug-info component cannot map the event to
       its source location: it emits the original LTTng event which has no
       special debug_info context field.

   LTTng prerequisites
       A filter.lttng-utils.debug-info component can only analyze user space
       events generated by LTTng (see <http://lttng.org>) 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 ldd(1)):

        1. Add the ip and vpid context fields to user space event records:

               $ lttng add-context --userspace --type=ip --type=vpid

           See lttng-add-context(1) for more details.

        2. Enable the LTTng-UST state dump events:

               $ lttng enable-event --userspace 'lttng_ust_statedump:*'

           See lttng-enable-event(1) and lttng-ust(3) for more details.

       To get debugging information for LTTng-UST events which occur in
       dynamically loaded objects, for example plugins:

        1. Do the previous steps (add context fields and enable the
           LTTng-UST state dump events).

        2. Enable the LTTng-UST dynamic linker tracing helper events:

               $ lttng enable-event --userspace 'lttng_ust_dl:*'

           See lttng-ust-dl(3) for more details.

        3. When you are ready to trace, start your application with the
           LD_PRELOAD environment variable set to liblttng-ust-dl.so:

               $ 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 Debugging
       Information in Separate Files (see
       <https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-
       Files.html>) section of GDB’s documentation.

       A filter.lttng-utils.debug-info 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:

        1. Within the executable file itself.

        2. Through the build ID method in the /usr/lib/debug/.build-id
           directory.

        3. In the various possible debug link locations.

       The component uses the first debugging information file that it
       finds.

       You can use the 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 filter.lttng-utils.debug-
       info 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 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         top

       The following parameters are optional.

       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.

       debug-info-field-name=NAME (string)
           Name the debugging information structure field in the context of
           the created events NAME instead of the default debug_info.

       full-path=yes (boolean)
           Use the full path when writing the executable name (bin) and
           source file name (src) fields in the debug_info context field of
           the created events.

       target-prefix=DIR (string)
           Use DIR as the root directory of the target file system instead
           of /.

PORTS         top

   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         top

       This component class has no objects to query.

ENVIRONMENT VARIABLES         top

       BABELTRACE_COMMON_LOG_LEVEL
           Common functions’s log level. The available values are the same
           as for the --log-level option of babeltrace(1).

       BABELTRACE_COMPAT_LOG_LEVEL
           Compatibility functions’s log level. The available values are the
           same as for the --log-level option of 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.

       BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL
           Component class’s log level. The available values are the same as
           for the --log-level option of babeltrace(1).

BUGS         top

       If you encounter any issue or usability problem, please report it on
       the Babeltrace bug tracker (see
       <https://bugs.linuxfoundation.org/buglist.cgi?product=Diamon&component=Babeltrace>).

RESOURCES         top

       The Babeltrace project shares some communication channels with the
       LTTng project (see <http://lttng.org/>).

       ·   Babeltrace website (see <http://diamon.org/babeltrace>)

       ·   Git repository (see
           <http://git.linuxfoundation.org/?p=diamon/babeltrace.git>)

       ·   EfficiOS GitHub organization (see <http://github.com/efficios/>)

       ·   Continuous integration (see
           <https://ci.lttng.org/job/babeltrace_master_build/>)

       ·   Mailing list (see <http://lists.lttng.org>) for support and
           development: lttng-dev@lists.lttng.org

       ·   IRC channel (see <irc://irc.oftc.net/lttng>): #lttng on
           irc.oftc.net

AUTHORS         top

       The Babeltrace project is the result of efforts by many regular
       developers and occasional contributors.

       The current project maintainer is Jérémie Galarneau
       <mailto:jeremie.galarneau@efficios.com>.

COPYRIGHT         top

       This component class is part of the Babeltrace project.

       Babeltrace is distributed under the MIT license (see
       <https://opensource.org/licenses/MIT>).

SEE ALSO         top

       babeltrace-plugin-lttng-utils(7), lttng(1), lttng-add-context(1),
       babeltrace-intro(7)

COLOPHON         top

       This page is part of the babeltrace (trace read and write libraries
       and a trace converter) project.  Information about the project can be
       found at ⟨http://www.efficios.com/babeltrace⟩.  If you have a bug
       report for this manual page, send it to lttng-dev@lists.lttng.org.
       This page was obtained from the project's upstream Git repository
       ⟨git://git.efficios.com/babeltrace.git⟩ on 2018-04-30.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2018-03-26.)  If you discover any rendering problems in
       this HTML version of the page, or you believe there is a better or
       more up-to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not part
       of the original manual page), send a mail to man-pages@man7.org

Babeltrace 2.0.0-pre4          5 October 2017           BABELTRACE-FILTER(7)

Pages that refer to this page: babeltrace(1)babeltrace-convert(1)babeltrace-plugin-lttng-utils(7)