doc/man/babeltrace2-filter.lttng-utils.debug-info.7.txt

   1 = babeltrace2-filter.lttng-utils.debug-info(7)
   2 :manpagetype: component class
   3 :revdate: 14 September 2019
   4 :compcls: compcls:filter.lttng-utils.debug-info
   5 :defdebuginfoname: `debug_info`
   6
   7
   8 == NAME
   9
  10 babeltrace2-filter.lttng-utils.debug-info - Babeltrace 2's debugging
  11 information filter component class for LTTng traces
  12
  13
  14 == DESCRIPTION
  15
  16 A Babeltrace~2 {compcls} message iterator creates and emits copies of
  17 upstream messages, augmenting LTTng event messages with debugging
  18 information when it's available and possible.
  19
  20 ----
  21 Messages without
  22 debugging information
  23   |
  24   |  +----------------------------+
  25   |  | flt.lttng-utils.debug-info |
  26   |  |                            |
  27   '->@ in                     out @--> Messages with
  28      +----------------------------+    debugging information
  29 ----
  30
  31 include::common-see-babeltrace2-intro.txt[]
  32
  33 A {compcls} message iterator uses the LTTng state dump events as well as
  34 the event common context's `ip` (instruction pointer) and `vpid`
  35 (process ID) fields to locate and read the corresponding debugging
  36 information. The message iterator can find the extra debugging
  37 information in an executable file or in a directory containing debugging
  38 information which the compiler creates.
  39
  40 The new LTTng events (copies of the original ones with added debugging
  41 information) contain, when possible, a new event common context's
  42 structure field (besides the `ip` field) named {defdebuginfoname} by
  43 default (you can use the param:debug-info-field-name parameter to choose
  44 another name). This structure field contains the following fields:
  45
  46 `bin` vtype:[string]::
  47     Executable path or name followed with `@ADDR` or `+ADDR`, where
  48     `ADDR` is the address (hexadecimal) where it was loaded while being
  49     traced.
  50 +
  51 `@ADDR` means `ADDR` is an absolute address, and `+ADDR` means `ADDR` is
  52 a relative address.
  53 +
  54 Examples: `my-program@0x4b7fdd23`, `my-program+0x18d7c`.
  55
  56 [[field-func]]`func` vtype:[string]::
  57     Function name followed with `+OFFSET`, where `OFFSET` is the offset
  58     (hexadecimal) from the beginning of the function symbol in the
  59     executable file.
  60 +
  61 Example: `load_user_config+0x194`.
  62
  63 [[field-src]]`src` vtype:[string]::
  64     Source file path or name followed with `:LINE`, where `LINE` is the
  65     line number in this source file at which the event occurred.
  66 +
  67 Example: `user-config.c:1025`.
  68
  69 Any of the previous fields can be an empty string if the debugging
  70 information was not available for the analyzed original LTTng event.
  71
  72 A {compcls} message iterator systematically copies the upstream
  73 messages, but it only augments compatible LTTng event classes. This
  74 means that the message iterator copies messages of non-LTTng trace (see
  75 <<lttng-prereq,``LTTng prerequisites''>>) without alteration.
  76
  77
  78 === Compile an executable for debugging information analysis
  79
  80 With GCC or Clang, you need to compile the program or library source
  81 files in debug mode with the nlopt:-g option. This option makes the
  82 compiler generate debugging information in the operating system's native
  83 format. This format is recognized by a {compcls} component: it can
  84 translate the instruction pointer field of an event's common context to
  85 a source file and line number, along with the name of the surrounding
  86 function.
  87
  88 IMPORTANT: This component class only supports the debugging information
  89 in DWARF format, version~2 or later. Use the nlopt:-gdwarf or
  90 nlopt:-gdwarf-VERSION (where `VERSION` is the DWARF version) compiler
  91 options to explicitly generate DWARF debugging information.
  92
  93 If you don't compile the executable's source files with the nlopt:-g
  94 option or with an equivalent option, no DWARF information is available:
  95 the message iterator uses ELF symbols from the executable file instead.
  96 In this case, the events that the message iterator creates do not
  97 contain the source file and line number (see the <<field-src,`src`
  98 field>>), but only the name of the nearest function symbol with an
  99 offset in bytes to the location in the executable from which the LTTng
 100 event occurred (see the <<field-func,`func` field>>).
 101
 102 If the executable file has neither ELF symbols nor DWARF information,
 103 the {compcls} message iterator cannot map the event to its source
 104 location: the message iterator still copies the upstream messages but
 105 without altering them.
 106
 107
 108 [[lttng-prereq]]
 109 === LTTng prerequisites
 110
 111 A {compcls} message iterator can only analyze user space events which
 112 https://lttng.org[LTTng]~2.8.0 or later generates.
 113
 114 To get debugging information for LTTng-UST events which occur in
 115 executables and libraries which the system's loader loads (what
 116 you can see with man:ldd(1)):
 117
 118 . Add the `ip` and `vpid` context fields to user space event records:
 119 +
 120 --
 121 [role="term"]
 122 ----
 123 $ lttng add-context --userspace --type=ip --type=vpid
 124 ----
 125 --
 126 +
 127 See man:lttng-add-context(1) for more details.
 128
 129 . Enable the LTTng-UST state dump events:
 130 +
 131 --
 132 [role="term"]
 133 ----
 134 $ lttng enable-event --userspace 'lttng_ust_statedump:*'
 135 ----
 136 --
 137 +
 138 See man:lttng-enable-event(1) and man:lttng-ust(3) for more details.
 139
 140 To get debugging information for LTTng-UST events which occur in
 141 dynamically loaded objects, for example plugins:
 142
 143 . Do the previous steps (add context fields and enable
 144   the LTTng-UST state dump events).
 145
 146 . Enable the LTTng-UST dynamic linker tracing helper events:
 147 +
 148 --
 149 [role="term"]
 150 ----
 151 $ lttng enable-event --userspace 'lttng_ust_dl:*'
 152 ----
 153 --
 154 +
 155 See man:lttng-ust-dl(3) for more details.
 156
 157 . When you are ready to trace, start your application with the
 158   `LD_PRELOAD` environment variable set to `liblttng-ust-dl.so`:
 159 +
 160 --
 161 [role="term"]
 162 ----
 163 $ LD_PRELOAD=liblttng-ust-dl.so my-app
 164 ----
 165 --
 166
 167
 168 === Separate debugging information
 169
 170 You can store DWARF debugging information outside the executable itself,
 171 whether it is to reduce the executable's file size or simply to
 172 facilitate sharing the debugging information.
 173
 174 This is usually achieved via one of two mechanisms, namely _build ID_
 175 and _debug link_. Their use and operation is described in the
 176 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging
 177 Information in Separate Files] section of GDB's documentation.
 178
 179 A {compcls} message iterator can find separate debugging information
 180 files automatically, as long as they meet the requirements stated in
 181 this manual page.
 182
 183 The debugging information lookup order is the same as GDB's, namely:
 184
 185 . Within the executable file itself.
 186
 187 . Through the build ID method in the `/usr/lib/debug/.build-id`
 188   directory.
 189
 190 . In the various possible debug link locations.
 191
 192 The message iterator uses the first debugging information file that it
 193 finds.
 194
 195 You can use the param:debug-info-dir initialization parameter to
 196 override the default `/usr/lib/debug` directory used in the build ID and
 197 debug link methods.
 198
 199 NOTE: It is currently not possible to make this component search for
 200 debugging information in multiple directories.
 201
 202
 203 === Target prefix
 204
 205 The debugging information analysis that a {compcls} message iterator
 206 performs uses the paths to the executables as collected during tracing
 207 as the default mechanism to resolve DWARF and ELF information.
 208
 209 If the trace was recorded on a separate machine, however, you can use
 210 the param:target-prefix parameter to specify a prefix directory, that
 211 is, the root of the target file system.
 212
 213 For example, if an instrumented executable's path is `/usr/bin/foo` on
 214 the target system, you can place this file at
 215 `/home/user/target/usr/bin/foo` on the system on which you use a
 216 {compcls} component. In this case, the target prefix to use is
 217 `/home/user/target`.
 218
 219
 220 == INITIALIZATION PARAMETERS
 221
 222 param:debug-info-dir='DIR' vtype:[optional string]::
 223     Use 'DIR' as the directory from which to load debugging information
 224     with the build ID and debug link methods instead of
 225     `/usr/lib/debug`.
 226
 227 param:debug-info-field-name='NAME' vtype:[optional string]::
 228     Name the debugging information structure field in the common context
 229     of the created events 'NAME' instead of the default
 230     {defdebuginfoname}.
 231
 232 param:full-path=`yes` vtype:[optional boolean]::
 233     Use the full path when writing the executable name (`bin`) and
 234     source file name (`src`) fields in the {defdebuginfoname} context
 235     field of the created events.
 236
 237 param:target-prefix='DIR' vtype:[optional string]::
 238     Use 'DIR' as the root directory of the target file system instead of
 239     `/`.
 240
 241
 242 == PORTS
 243
 244 ----
 245 +----------------------------+
 246 | flt.lttng-utils.debug-info |
 247 |                            |
 248 @ in                     out @
 249 +----------------------------+
 250 ----
 251
 252
 253 === Input
 254
 255 `in`::
 256     Single input port.
 257
 258
 259 === Output
 260
 261 `out`::
 262     Single output port.
 263
 264
 265 include::common-footer.txt[]
 266
 267
 268 == SEE ALSO
 269
 270 man:babeltrace2-intro(7),
 271 man:babeltrace2-plugin-lttng-utils(7),
 272 man:lttng(1),
 273 man:lttng-add-context(1)