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

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