Messages without debugging information | | +----------------------------+ | | flt.lttng-utils.debug-info | | | | '->@ in out @--> Messages with +----------------------------+ debugging information
See babeltrace2-intro(7) to learn more about the Babeltrace 2 project and its core concepts.
A filter.lttng-utils.debug-info message iterator uses the LTTng state dump events as well as the event common context’s ip (instruction pointer) and vpid (process ID) fields to locate and read the corresponding debugging information. The message iterator can find the extra debugging information in an executable file or in a directory containing debugging information which the compiler creates.
The new LTTng events (copies of the original ones with added debugging information) contain, when possible, a new event common context’s structure field (besides the ip field) named debug_info by default (you can use the debug-info-field-name parameter to choose another name). This structure field contains the following fields:
@ADDR means ADDR is an absolute address, and +ADDR means ADDR is a relative address.
Examples: my-program@0x4b7fdd23, my-program+0x18d7c.
Any of the previous fields can be an empty string if the debugging information was not available for the analyzed original LTTng event.
A filter.lttng-utils.debug-info message iterator systematically copies the upstream messages, but it only augments compatible LTTng event classes. This means that the message iterator copies messages of non-LTTng trace (see “LTTng prerequisites”) without alteration.
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 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.
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)):
$ lttng add-context --userspace --type=ip --type=vpid
See lttng-add-context(1) for more details.
$ lttng enable-event --userspace 'lttng_ust_statedump:*'
To get debugging information for LTTng-UST events which occur in dynamically loaded objects, for example plugins:
$ lttng enable-event --userspace 'lttng_ust_dl:*'
See lttng-ust-dl(3) for more details.
$ LD_PRELOAD=liblttng-ust-dl.so my-app
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:
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.
It is currently not possible to make this component search for debugging information in multiple directories.
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.
debug-info-field-name=NAME [optional string]
full-path=yes [optional boolean]
target-prefix=DIR [optional string]
+----------------------------+ | flt.lttng-utils.debug-info | | | @ in out @ +----------------------------+
The current project maintainer is Jérémie Galarneau <mailto:email@example.com>.
Babeltrace is distributed under the MIT license (see https://opensource.org/licenses/MIT).