Python bindings: make intersect_mode read-only property

[babeltrace.git] / doc / debuginfo.txt

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 <path/to/trace>

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" <path/to/executable>

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/.