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

   1 babeltrace-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 babeltrace-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:babeltrace-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 The filter component needs the LTTng-UST events to contain the
 101 `ip` and `vpid` fields in their context.
 102
 103 To add those context fields with the man:lttng(1) command-line tool
 104 before the tracers are active (before `lttng start`):
 105
 106 [role="term"]
 107 ----
 108 $ lttng add-context --userspace --type=ip --type=vpid
 109 ----
 110
 111 See man:lttng-add-context(1) for more information.
 112
 113 To get debugging information for LTTng-UST events which occur in
 114 dynamically loaded objects, for example plugins, start the application
 115 to trace with the LTTng-UST dynamic linking helper:
 116
 117 [role="term"]
 118 ----
 119 $ LD_PRELOAD=liblttng-ust-dl.so my-app
 120 ----
 121
 122 See man:lttng-ust-dl(3) for more information.
 123
 124
 125 Separate debugging information
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 127 It is possible to store DWARF debugging information outside the
 128 executable itself, whether it is to reduce the executable's file size,
 129 or simply to facilitate the sharing of the debugging information.
 130
 131 This is usually achieved via one of two mechanisms, namely _build ID_
 132 and _debug link_. Their use and operation is described in the
 133 https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html[Debugging
 134 Information in Separate Files] section of GDB's documentation.
 135
 136 A {comp} component can find separate debugging information files
 137 automatically, as long as they meet the requirements stated in this man
 138 page.
 139
 140 The debugging information lookup order is the same as GDB's, namely:
 141
 142 . Within the executable file itself.
 143
 144 . Through the build ID method in the `/usr/lib/debug/.build-id`
 145   directory.
 146
 147 . In the various possible debug link locations.
 148
 149 The component uses the first debugging information file that it finds.
 150
 151 You can use the param:deubg-info-dir initialization parameter to
 152 override the default `/usr/lib/debug` directory used in the build ID and
 153 debug link methods.
 154
 155 NOTE: It is currently not possible to make this component search for
 156 debugging information in multiple directories.
 157
 158
 159 Target prefix
 160 ~~~~~~~~~~~~~
 161 The debugging information analysis that a {comp} component performs uses
 162 the paths to the executables as collected during tracing as the default
 163 mechanism to resolve DWARF and ELF information.
 164
 165 If the trace was recorded on a separate machine, however, you can use
 166 the param:target-prefix parameter to specify a prefix directory, that
 167 is, the root of the target file system.
 168
 169 For example, if an instrumented executable's path is `/usr/bin/foo` on
 170 the target system, you can place this file at
 171 `/home/user/target/usr/bin/foo` on the system on which you use the
 172 component. In this case, the target prefix to use is
 173 `/home/user/target`.
 174
 175
 176 INITIALIZATION PARAMETERS
 177 -------------------------
 178 The following parameters are optional.
 179
 180 param:debug-info-dir='DIR' (string)::
 181     Use 'DIR' as the directory from which to load debugging information
 182     with the build ID and debug link methods instead of
 183     `/usr/lib/debug`.
 184
 185 param:debug-info-field-name='NAME' (string)::
 186     Name the debugging information structure field in the context of
 187     the created events 'NAME' instead of the default {defdebuginfoname}.
 188
 189 param:full-path=`yes` (boolean)::
 190     Use the full path when writing the executable name (`bin`) and
 191     source file name (`src`) fields in the {defdebuginfoname} context
 192     field of the created events.
 193
 194 param:target-prefix='DIR' (string)::
 195     Use 'DIR' as the root directory of the target file system instead of
 196     `/`.
 197
 198
 199 PORTS
 200 -----
 201 Input
 202 ~~~~~
 203 `in`::
 204     Single input port from which the component receives the
 205     notifications to augment with debugging information.
 206
 207
 208 Output
 209 ~~~~~~
 210 `out`::
 211     Single output port to which the component sends the augmented
 212     or unaltered notifications.
 213
 214
 215 QUERY OBJECTS
 216 -------------
 217 This component class has no objects to query.
 218
 219
 220 ENVIRONMENT VARIABLES
 221 ---------------------
 222 include::common-common-compat-env.txt[]
 223
 224 `BABELTRACE_FLT_LTTNG_UTILS_DEBUG_INFO_LOG_LEVEL`::
 225     Component class's log level. The available values are the
 226     same as for the manopt:babeltrace(1):--log-level option of
 227     man:babeltrace(1).
 228
 229
 230 include::common-footer.txt[]
 231
 232
 233 SEE ALSO
 234 --------
 235 man:babeltrace-plugin-lttng-utils(7),
 236 man:lttng(1),
 237 man:lttng-add-context(1),
 238 man:babeltrace-intro(7)