Add modern Babeltrace man pages

[babeltrace.git] / doc / man / babeltrace-filter.lttng-utils.debug-info.7.txt

babeltrace-filter.lttng-utils.debug-info(7)
===========================================
:manpagetype: component class
:revdate: 5 October 2017
:comp: compcls:filter.lttng-utils.debug-info
:defdebuginfoname: `debug_info`


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


DESCRIPTION
-----------
The Babeltrace {comp} component class, provided by the the
man:babeltrace-plugin-lttng-utils(7) plugin, once instantiated, receives
events from http://lttng.org/[LTTng] traces and creates new ones
which are copies of the original ones with extra debugging information
when it's available and possible.

A {comp} 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 {defdebuginfoname} 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`.

[[field-func]]`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`.

[[field-src]]`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 nlopt:-g option. This option makes the
compiler generate debugging information in the operating system's native
format. This format is recognized by a {comp} 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{nbsp}2 or later. Use the nlopt:-gdwarf or
nlopt:-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 nlopt:-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 (<<field-src,`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 (<<field-func,`func`
field>>).

If the executable file has neither ELF symbols nor DWARF information,
the {comp} component cannot map the event to
its source location: it emits the original LTTng event which has no
special {defdebuginfoname} context field.


LTTng prerequisites
~~~~~~~~~~~~~~~~~~~
A {comp} component can only analyze user space events generated by
http://lttng.org[LTTng]{nbsp}2.8.0 or later.

The filter component needs the LTTng-UST events to contain the
`ip` and `vpid` fields in their context.

To add those context fields with the man:lttng(1) command-line tool
before the tracers are active (before `lttng start`):

[role="term"]
----
$ lttng add-context --userspace --type=ip --type=vpid
----

See man:lttng-add-context(1) for more information.

To get debugging information for LTTng-UST events which occur in
dynamically loaded objects, for example plugins, start the application
to trace with the LTTng-UST dynamic linking helper:

[role="term"]
----
$ LD_PRELOAD=liblttng-ust-dl.so my-app
----

See man:lttng-ust-dl(3) for more information.


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
https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging
Information in Separate Files] section of GDB's documentation.

A {comp} 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:

. Within the executable file itself.

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

. In the various possible debug link locations.

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

You can use the param: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 {comp} 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 param: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
-------------------------
The following parameters are optional.

param: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`.

param:debug-info-field-name='NAME' (string)::
    Name the debugging information structure field in the context of
    the created events 'NAME' instead of the default {defdebuginfoname}.

param:full-path=`yes` (boolean)::
    Use the full path when writing the executable name (`bin`) and
    source file name (`src`) fields in the {defdebuginfoname} context
    field of the created events.

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


PORTS
-----
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
-------------
This component class has no objects to query.


ENVIRONMENT VARIABLES
---------------------
include::common-common-compat-env.txt[]

`BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`::
    Component class's log level. The available values are the
    same as for the manopt:babeltrace(1):--log-level option of
    man:babeltrace(1).


include::common-footer.txt[]


SEE ALSO
--------
man:babeltrace-plugin-lttng-utils(7),
man:lttng(1),
man:lttng-add-context(1),
man:babeltrace-intro(7)