babeltrace2-filter.lttng-utils.debug-info

With GCC or Clang, you need to 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 common context to a source file and line number, along with the name of the surrounding function.

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 message iterator uses ELF symbols from the executable file instead. In this case, the events that the message iterator creates do not contain the source file and line number (see the 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 occurred (see the func field).

If the executable file has neither ELF symbols nor DWARF information, the filter.lttng-utils.debug-info message iterator cannot map the event to its source location: the message iterator still copies the upstream messages but without altering them.

A filter.lttng-utils.debug-info message iterator can only analyze user space events which LTTng (see <https://lttng.org>) 2.8.0 or later generates.

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

You can store DWARF debugging information outside the executable itself, whether it is to reduce the executable’s file size or simply to facilitate sharing 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 message iterator can find separate debugging information files automatically, as long as they meet the requirements stated in this manual 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 message iterator uses the first debugging information file that it finds.

You can use the debug-info-dir initialization parameter to override the default /usr/lib/debug directory used in the build ID and debug link methods.

The debugging information analysis that a filter.lttng-utils.debug-info message iterator 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 a filter.lttng-utils.debug-info component. In this case, the target prefix to use is /home/user/target.

in

Single input port.

out

Single output port.