| 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) |