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