--- /dev/null
+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:
+
+ [...]
+ [19:53:41.648394410] (+0.000022616) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB4D4, debug_info = { func = "foo", source_loc = "/home/efficios/example/libhello.c:7" }, vpid = 25577 }, { my_string_field = "hello, tracer", my_integer_field = 42 }
+ [19:53:41.648423786] (+0.000029376) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB5A6, debug_info = { func = "bar", source_loc = "/home/efficios/example/libhello.c:13" }, vpid = 25577 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 }
+ [19:53:41.648435726] (+0.000011940) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB66B, debug_info = { func = "baz", source_loc = "/home/efficios/example/libhello.c:20" }, vpid = 25577 }, { some_field = 1729 }
+ [...]
+
+The interesting part is the debug_info section of the context:
+
+ debug_info = { func = "foo", source_loc = "/home/efficios/example/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
+function containing the tracepoint instance which generated the event
+("foo"), 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:
+
+ [...]
+ [19:53:41.648394410] (+0.000022616) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB4D4, debug_info = { func = "foo+0xa9" }, vpid = 25577 }, { my_string_field = "hello, tracer", my_integer_field = 42 }
+ [19:53:41.648423786] (+0.000029376) colossus my_provider:my_first_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB5A6, debug_info = { func = "bar+0xa9" }, vpid = 25577 }, { my_string_field = "recoltes et semailles", my_integer_field = 57 }
+ [19:53:41.648435726] (+0.000011940) colossus my_provider:my_other_tracepoint: { cpu_id = 2 }, { ip = 0x7F75AEDFB66B, debug_info = { func = "baz+0x9c" }, vpid = 25577 }, { some_field = 1729 }
+ [...]
+
+The debug information now provides only the function name as given by
+ELF symbols, plus an offset in bytes from the symbol to the actual
+location of the tracepoint instance.
+
+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.
+
+Debug Info Directory
+--------------------
+
+When performing debug info analysis, babeltrace uses an executable's
+path from when it was traced to resolve debug information. If,
+however, the trace was taken on a different machine, or the executable
+was simply moved since the trace was taken, it is possible to override
+the base path from which to look for the debug information. To do so,
+the --debug-info-dir babeltrace command-line flag is available.
+
+If a --debug-info-dir value is given, it will replace the default
+/usr/lib/debug path used in build ID and debug link lookups.
+
+Note that multiple debug directories are not currently supported.
projects / babeltrace.git / commitdiff
