doc/man: make default values of boolean init. params. clearer

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

= babeltrace2-filter.lttng-utils.debug-info(7)
:manpagetype: component class
:revdate: 1 September 2023
:compcls: compcls:filter.lttng-utils.debug-info
:defdebuginfoname: `debug_info`


== NAME

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


== DESCRIPTION

A Babeltrace~2 {compcls} message iterator creates and emits copies of
upstream messages, augmenting LTTng event messages with debugging
information when it's available and possible.

----
Messages without
debugging information
  |
  |  +----------------------------+
  |  | flt.lttng-utils.debug-info |
  |  |                            |
  '->@ in                     out @--> Messages with
     +----------------------------+    debugging information
----

include::common-see-babeltrace2-intro.txt[]

A {compcls} 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 {defdebuginfoname} by
default (you can use the param:debug-info-field-name parameter to choose
another name). This structure field contains the following fields:

`bin` vtype:[string]::
    Executable path or name followed with `@ADDR` or `+ADDR`, where
    `ADDR` is the address (hexadecimal) where it was loaded while being
    traced.
+
`@ADDR` means `ADDR` is an absolute address, and `+ADDR` means `ADDR` is
a relative address.
+
Examples: `my-program@0x4b7fdd23`, `my-program+0x18d7c`.

[[field-func]]`func` vtype:[string]::
    Function name followed with `+OFFSET`, where `OFFSET` is the offset
    (hexadecimal) from the beginning of the function symbol in the
    executable file.
+
Example: `load_user_config+0x194`.

[[field-src]]`src` vtype:[string]::
    Source file path or name followed with `:LINE`, where `LINE` is the
    line number in this source file at which the event occurred.
+
Example: `user-config.c:1025`.

Any of the previous fields can be an empty string if the debugging
information was not available for the analyzed original LTTng event.

A {compcls} 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-prereq,``LTTng prerequisites''>>) without alteration.


=== Compile an executable for debugging information analysis

With GCC or Clang, you need to 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 {compcls} 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.

IMPORTANT: This component class only supports the debugging information
in DWARF format, version~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 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 <<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 occurred (see the <<field-func,`func` field>>).

If the executable file has neither ELF symbols nor DWARF information,
the {compcls} message iterator cannot map the event to its source
location: the message iterator still copies the upstream messages but
without altering them.


[[lttng-prereq]]
=== LTTng prerequisites

A {compcls} message iterator can only analyze user space events which
https://lttng.org[LTTng]~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 man:ldd(1)):

. Add the `ip` and `vpid` context fields to user space event records:
+
--
[role="term"]
----
$ lttng add-context --userspace --type=ip --type=vpid
----
--
+
See man:lttng-add-context(1) for more details.

. Enable the LTTng-UST state dump events:
+
--
[role="term"]
----
$ lttng enable-event --userspace 'lttng_ust_statedump:*'
----
--
+
See man:lttng-enable-event(1) and man:lttng-ust(3) for more details.

To get debugging information for LTTng-UST events which occur in
dynamically loaded objects, for example plugins:

. Do the previous steps (add context fields and enable
  the LTTng-UST state dump events).

. Enable the LTTng-UST dynamic linker tracing helper events:
+
--
[role="term"]
----
$ lttng enable-event --userspace 'lttng_ust_dl:*'
----
--
+
See man:lttng-ust-dl(3) for more details.

. When you are ready to trace, start your application with the
  `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`:
+
--
[role="term"]
----
$ LD_PRELOAD=liblttng-ust-dl.so my-app
----
--


=== Separate debugging information

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

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

. 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 message iterator uses the first debugging information file that it
finds.

You can use the param:debug-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 {compcls} 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 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 a
{compcls} component. In this case, the target prefix to use is
`/home/user/target`.


== INITIALIZATION PARAMETERS

param:debug-info-dir='DIR' vtype:[optional 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' vtype:[optional string]::
    Name the debugging information structure field in the common context
    of the created events 'NAME' instead of the default
    {defdebuginfoname}.

param:full-path='VAL' vtype:[optional boolean]::
    If 'VAL' is true, then 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.
+
Default: false.

param:target-prefix='DIR' vtype:[optional string]::
    Use 'DIR' as the root directory of the target file system instead of
    `/`.


== PORTS

----
+----------------------------+
| flt.lttng-utils.debug-info |
|                            |
@ in                     out @
+----------------------------+
----


=== Input

`in`::
    Single input port.


=== Output

`out`::
    Single output port.


include::common-footer.txt[]


== SEE ALSO

man:babeltrace2-intro(7),
man:babeltrace2-plugin-lttng-utils(7),
man:lttng(1),
man:lttng-add-context(1)